README.md

elm-spinner

A highly configurable, efficiently rendered spinner component.

The Spinner module exposes the Model and Msg type as well as an update and view function, all ready to with the Elm Architecture in your application.

Features:

• No images, no external CSS
• Highly configurable (try the interactive spinner editor)
• Resolution independent (looks great on Retina!!)
• Efficient animations thanks to window.requestAnimationFrame
• Works in Chrome, Safari, Firefox from IE >= 10

Reference:

• license
• bug tracker
• source code
• documentation
• changelog

Quickstart

This section will walk you through your very first steps with the Spinner module. At the end, you'll have a good understanding of how to use this module.

You can find two complete examples in the example/ folder:

• A simple, bare bones integration of a spinner in example/simple/
• A visual spinner editor, allowing you to make your own spinner in example/editor/

If you're not yet familiar with The Elm Architecture, give it a quick read. It will help you to understand how the spinner works.

Preparation: Import the module

Run the following command in the root directory of your project:

elm package install damienklinnert/elm-spinner

And then import the Spinner module at the top of a module like this:

import Spinner

Now you're ready to wire up everything!

Subscription

Since our spinner is animated, we'll need to add a subscription to our program:

main : Program Never Model Msg
main =
    program
        { init = init
        , update = update
        , view = view
        , subscriptions = (\model -> Sub.map SpinnerMsg Spinner.subscription)
        }

Update Function

You might have already noticed the SpinnerMsg in the previous example. Since our spinner is animated, it will send messages of type Spinner.Msg wrapped inside a SpinnerMsg to our update function.

Now it's up to us to forward those messages to the Spinner.update function:

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        Noop ->
            model ! []

        SpinnerMsg msg ->
            let
                spinnerModel =
                    Spinner.update msg model.spinner
            in
                { model | spinner = spinnerModel } ! []

Model

The previous example already referenced model.spinner, which is of type Spinner.Model. The Spinner.update function takes care of keeping that up to date for us. However we still need to add Spinner.Model to our applications model.

type alias Model =
    { spinner : Spinner.Model
    }

Now where Spinner.Model is part of your model, you also need to properly initialise it. You can use Spinner.init to get started quickly:

init : ( Model, Cmd Msg )
init =
    { spinner = Spinner.init } ! []

View

Now, last but not least, you can add the spinner to your application's view like this:

view : Model -> Html.Html Msg
view model =
    Html.div [] [ Spinner.view Spinner.defaultConfig model.spinner ]

Et Voilà, you should now have an animated spinner in your application.

Note: If you dislike the default spinner stype, you can make your own. Check the spin module docs for more info.

What's next?

• Check the bare bones integration
• Make your own spinner
• Check out the full documentation for the Spin module

Credits

This module is highly inspired by spin.js from Felix Gnass.