A timeline of state values.

Behind the scenes this is roughly a list of states and the times that they should occur!

Create a timeline with an initial state.

So, if you previously had a Bool in your model:

type alias Model = { checked : Bool }


-- created via
{ checked = False }

You could replace that with an Animator.Timeline Bool

type alias Model = { checked : Animator.Timeline Bool }


-- created via
{ checked = Animator.init False }

Get the current state of the timeline.

This value will switch to a new value when a transition begins.

If you had a timeline that went from A to B to C, here's what current would be at various points on the timeline.

          A---------B---------C
               ^    ^    ^    ^
current:       B    B    C    C

Note — If you want to detect the moment when you arrive at a new state, try using arrivedAt

Get the previous state on this timeline.

As you'll see in the Loading example, it means we can use previous to refer to data that we've already "deleted" or set to Nothing.

How cool!

          A---------B---------C
               ^    ^    ^
previous:      A    A    B

Check to see if a state is upcoming on a timeline.

Note — This can be used to ensure a set of states can only be queued if they aren't already running.

Note 2 — This only checks if an event is in the future, but does not check the value you're currently at. You might need to use arrived as well if you also care about the current state.

For complicated values it can be computationally expensive to use ==.

upcomingWith allows you to specify your own equality function, so you can be smarter in checking how two value are equal.

Subtley different than current, this will provide the new state as soon as the transition has finished.

          A---------B---------C
               ^    ^    ^    ^
arrived:       A    B    B    C

Sometimes we want to know when we've arrived at a state so we can trigger some other work.

You can use arrivedAt in the Tick branch of your update to see if you will arrive at an event on this tick.

Tick time ->
    if Animator.arrivedAt MyState time model.timeline then
        --...do something special

Again, sometimes you'll want to supply your own equality function!

An Animator knows how to read and write all the Timelines within your Model.

Here's an animator from the Checkbox.elm example,

animator : Animator.Animator Model
animator =
    Animator.animator
        |> Animator.watching
            -- we tell the animator how
            -- to get the checked timeline using .checked
            .checked
            -- and we tell the animator how
            -- to update that timeline as well
            (\newChecked model ->
                { model | checked = newChecked }
            )

Notice you could add any number of timelines to this animator.

Note — You likely only need one animator for a given project.

Note 2 — Once we have an Animator Model, we have two more steps in order to set things up:

• create a subscription
• update our model

watching will ensure that AnimationFrame is running when the animator is transformed into a subscription.

Note — It will actually make the animation frame subscription run all the time! At some point you'll probably want to optimize when the subscription runs, which means either using watchingWith or Animator.Css.watching.

watchingWith will allow you to have more control over when AnimationFrame runs.

The main thing you need to do here is capture which states are animated when they're resting.

Let's say we have a checkbox that, for whatever reason, we want to say is spinning forever when the value is False.

animator : Animator.Animator Model
animator =
    Animator.animator
        |> Animator.watchingWith .checked
            (\newChecked model ->
                { model | checked = newChecked }
            )
            -- here is where we tell the animator that we still need
            -- AnimationFrame when the timeline has a current value of `False`
            (\checked ->
                checked == False
            )

Note — if you're using Animator.Css to generate keyframes along with Animator.Css.watching, you don't need to worry about this.

Convert an Animator to a subscription.

This is where the animator will decide if a running animation needs another frame or not.

subscriptions model =
    Animator.toSubscription Tick model animator

When new messages come in, we then need to update our model. This looks something like this:

type Msg
    = Tick Time.Posix


update msg model =
    case msg of
        Tick newTime ->
            ( Animator.update newTime animator model
            , Cmd.none
            )

And voilà, we can begin animating!

Note — To animate more things, all you need to do is add a new with to your Animator.

If you're creating something like a game, you might want to update your Timelines manually instead of using an Animator.

This will allow you to do whatever calculations you need while updating each Timeline.

Note — You'll have to take care of subscribing to Browser.Events.onAnimationFrame.

Go to a new state!

You'll need to specify a Duration as well. Try starting with Animator.quickly and adjust up or down as necessary.

Choosing a nice duration can depend on:

• The size of the thing moving
• The type of movement
• The distance it's traveling.

So, start with a nice default and adjust it as you start to understand your specific needs.

Note — Here's a very good overview on animation durations and speeds.

0ms

100ms.

200ms - Likely a good place to start!

400ms.

500ms.

Interrupt what's currently happening with a new list.

Wait until the current timeline is finished and then continue with these new steps.

Interpolate linearly between destinations. This is a shortcut to help you out.

You can do this with move by doing

Animator.move timeline <|
    \state ->
        if state then
            Animator.at 0
                |> Animator.leaveSmoothly 0
                |> Animator.arriveSmoothly 0


        else
            Animator.at 1
                |> Animator.leaveSmoothly 0
                |> Animator.arriveSmoothly 0

Which is equivalent to

Animator.linear timeline <|
    \state ->
        if state then
            Animator.at 0


        else
            Animator.at 1

Even though the transition officially starts at a certain time on the timeline, we can leave a little late.

• 0 means we leave at the normal time.
• 0.2 means we'll leave when the transition is at 20%.
• 1 means we leave at the end of the transition and instantly flip to the new state at that time.

We can also arrive early to this state.

• 0 means we arrive at the normal time.
• 0.2 means we'll arrive early by 20% of the total duration.
• 1 means we arrive at the start of the transition. So basically we instantly transition over.

Weird math note — arriveEarly and leaveLate will collaborate to figure out how the transition happens. If arriveEarly and leaveLate sum up to more 1 for a transition, then their sum will be the new maximum. Likely you don't need to worry about this :D.

The intended use for arriveEarly and leaveLate is for staggering items in a list. In those cases, these values are pretty small ~0.1.

Underneath the hood this library uses Bézier curves to model motion.

Because of this you can adjust the "smoothness" of the curve that's ultimately used.

• leaveSmoothly 0 is essentially linear animation.
• leaveSmoothly 1 means the animation will start slowly and smoothly begin to accelerate.

Here's a general diagram of what's going on:

Note — The values in the above diagram are the built in defaults for most movements in elm-animator. They come from Material Design.

Note 2 — An interactive version of the above diagram is also available.

We can also smooth out our arrival.

• arriveSmoothly 0 means no smoothing, which means more of a linear animation.
• arriveSmoothly 1 means the animation will "ease out" or "arrive slowly".

This will make the transition use a spring instead of bezier curves!

• withWobble 0 - absolutely no wobble
• withWobble 1 - all the wobble

Use your wobble responsibly.

This is basically a sine wave! It will "wave" between the two numbers you give it.

Start at one number and move linearly to another, then immediately start again at the first.

This was originally intended for animating rotation where you'd want 360deg to "wrap" to 0deg.

Start at one number, move linearly to another, and then linearly back.

Or make whatever kind of oscillator you need!

This takes a function which is given the progress of this oscillation as a Float between 0 and 1.

Shift an oscillator over by a certain amount.

It's expecting a number between 0 and 1.

Show a single sprite.

Show this sprite for a number of frames. Only really useful if you're using walk or cycle.

Walk through a list of frames as we're transitioning to this state.

Here we have the same distinction of transition and resting that the rest of the library has.

With framesWith we can define the frames it takes to transition to this state, as well as what to do when we're in this state (maybe we want to loop through a number of frames when we're in this state).

While we're at this specific state, cycle through a list of frames at this fps.

Same as cycle, but only for n number of times.