PackagesReroutesAboutlamdera.com

phollyer/elm-motion/2.1.3

NOTE: the latest version is 3.0.4

READMEAboutVersionsSourceModules

Anim.Engine.Keyframe

CSS keyframe animations with browser-native performance.

This engine is a good fit for 'on-load' animations, or if you need looping, alternating, or pause/resume functionality.

📖 See Keyframe Engine Documentation and Engine Overview for details.

Types

type alias AnimState =
AnimState

Holds the Keyframe engine state.

Keep this in your model.

type alias Model =
    { animState : Keyframe.AnimState }
type alias AnimGroupName =
String

The name of the animation group you want to target.

Builders

type alias AnimBuilder eng =
AnimBuilder eng

Type alias for the base AnimBuilder type.

Engine Builder

type alias EngineBuilder =
EngineBuilder

Builder type for Keyframe-only builders.

Use this in type annotations when a builder function should only work with this engine.

Equivalent to AnimBuilder ForKeyframe.

📖 See Engine Capabilities for patterns and examples.

Initialize

📖 See Initialize for details.

init : List (EngineBuilder -> EngineBuilder) -> AnimState

Initialize the engine state with optional property initializers.

import Anim.Engine.Keyframe as Keyframe
import Anim.Property.Opacity as Opacity


Keyframe.init
    [ Opacity.init "animGroupName" 0.5
    , ... -- other property initializers
    ]

Target

for : AnimGroupName -> EngineBuilder -> EngineBuilder

Select the animation group that subsequent property builders will target.

Keyframe.for "animGroupName"
    >> Opacity.begin
    >> Opacity.to 0.2
    >> Opacity.end

Trigger

📖 See Triggering Animations for details.

animate : AnimState -> (EngineBuilder -> EngineBuilder) -> AnimState

Trigger animations.

import Anim.Engine.Keyframe as Keyframe


{ model
    | animState =
        Keyframe.animate model.animState <|
            Keyframe.for "animGroupName"
                >> entryAnim
}
retarget : AnimState -> (EngineBuilder -> EngineBuilder) -> AnimState

Change the targeted properties instantly to their new values. If currently animating, stop.

This is a convenience function for immediately snapping properties or axes to new values without needing to construct a full animation builder with animate.

Just target the properties or axes you want to change. Any other properties or axes on the group will snap to their targeted end values if mid-flight.

import Anim.Engine.Keyframe as Keyframe
import Anim.Property.Translate as Translate


{ model
    | animState =
        Keyframe.retarget model.animState <|
            Keyframe.for "animGroupName"
                >> Translate.begin
                >> Translate.toY 0
                >> Translate.end
}

Events

📖 See Event Reference for details.

type alias CurrentTargetId =
Maybe String

The ID of the element that owns the event listener.

type alias TargetId =
Maybe String

The ID of the element that started the event.

This will be different from CurrentTargetId if the event bubbled from a child element.

= Ended CurrentTargetId TargetId AnimGroupName
| Cancelled CurrentTargetId TargetId AnimGroupName
| Iteration CurrentTargetId TargetId AnimGroupName Int
| Paused AnimGroupName
| Resumed AnimGroupName
| Restarted AnimGroupName
| Run CurrentTargetId TargetId AnimGroupName

CSS keyframe animation lifecycle events.

Update

📖 See React for details.

type alias AnimMsg =
AnimMsg

Message type used with update.

import Anim.Engine.Keyframe as Keyframe


type Msg
    = KeyframeMsg Keyframe.AnimMsg
    | ...
update : AnimMsg -> AnimState -> ( AnimState, Maybe AnimEvent )

Handle messages from this engine.

Returns the updated state and an event for this message, if one should be surfaced.

import Anim.Engine.Keyframe as Keyframe


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        KeyframeMsg animMsg ->
            let
                ( animState, maybeEvent ) =
                    Keyframe.update animMsg model.animState


                nextModel =
                    { model | animState = animState }
            in
            case maybeEvent of
                Just event ->
                    handleAnimationEvent event nextModel


                Nothing ->
                    ( nextModel, Cmd.none )


handleAnimationEvent : Keyframe.AnimEvent -> Model -> ( Model, Cmd Msg )
handleAnimationEvent event model =
    case event of
        ...

View

To render keyframes, add attributes to the element and include styleNode or styleNodeFor somewhere in your view.

📖 See Render and Keyframe Style Node for details.

attributes : AnimGroupName -> AnimState -> List (Attribute msg)

Apply the animation attributes to your element.

import Anim.Engine.Keyframe as Keyframe
import Html exposing (div, text)


div
    (Keyframe.attributes "animGroupName" animState)
    [ text "Animating element" ]
styleNode : AnimState -> Html msg

Get a <style> node containing the keyframes for all animations.

import Anim.Engine.Keyframe as Keyframe
import Html exposing (div)


view model =
    div []
        [ Keyframe.styleNode model.animState
        , ...
        ]

If there are no animations, this returns an empty text node.

styleNodeFor : AnimGroupName -> AnimState -> Html msg

Get a <style> node containing keyframes for a specific animation group.

import Anim.Engine.Keyframe as Keyframe
import Html exposing (div)


view model =
    div []
        [ Keyframe.styleNodeFor "animGroupName" model.animState
        , ...
        ]

If there are no animations, this returns an empty text node.

maybeString : AnimGroupName -> AnimState -> Maybe String

Get the raw generated CSS keyframes string for advanced use cases.

You probably want styleNodeFor instead, which handles creating the full <style> node for you.

Event Listeners

📖 See Events for details.

events : (AnimMsg -> msg) -> List (Attribute msg)

Receive keyframe animation lifecycle events.

Add events to your element with a message constructor that wraps AnimMsg.

import Anim.Engine.Keyframe as Keyframe
import Html exposing (div, text)


type Msg
    = KeyframeMsg Keyframe.AnimMsg


div
    (Keyframe.attributes "animGroupName" animState
        ++ Keyframe.events KeyframeMsg
    )
    [ text "Animating element" ]
eventsStopPropagation : (AnimMsg -> msg) -> List (Attribute msg)

The same as events but with propagation stopped.

import Anim.Engine.Keyframe as Keyframe
import Html exposing (div, text)


div
    (Keyframe.attributes "animGroupName" animState
        ++ Keyframe.eventsStopPropagation KeyframeMsg
    )
    [ text "Animated element" ]

Unit

cssUnit : Unit -> EngineBuilder -> EngineBuilder

Set the default length unit for all length-bearing properties.

responsivePanelMotion : EngineBuilder -> EngineBuilder
responsivePanelMotion =
    cssUnit Unit.Vw
        >> slidePanelIn
        >> growPanel
cssUnitX : Unit -> EngineBuilder -> EngineBuilder

Set the default length unit for the X axis.

responsiveDrawerMotion : EngineBuilder -> EngineBuilder
responsiveDrawerMotion =
    cssUnitX Unit.Vw
        >> slidePanelIn
        >> growPanel
cssUnitY : Unit -> EngineBuilder -> EngineBuilder

Set the default length unit for the Y axis.

responsiveSheetMotion : EngineBuilder -> EngineBuilder
responsiveSheetMotion =
    cssUnitY Unit.Vh
        >> slidePanelIn
        >> growPanel
cssUnitZ : Unit -> EngineBuilder -> EngineBuilder

Set the default length unit for the Z axis.

layeredSceneMotion : EngineBuilder -> EngineBuilder
layeredSceneMotion =
    cssUnitZ Unit.Px
        >> slidePanelIn
        >> growPanel
cssUnitWidth : Unit -> EngineBuilder -> EngineBuilder

Set the default length unit used for width values in Keyframe animations.

responsiveCardWidth : EngineBuilder -> EngineBuilder
responsiveCardWidth =
    cssUnitWidth Unit.Vw
        >> slidePanelIn
        >> growPanel
cssUnitHeight : Unit -> EngineBuilder -> EngineBuilder

Set the default length unit used for height values in Keyframe animations.

responsivePanelHeight : EngineBuilder -> EngineBuilder
responsivePanelHeight =
    cssUnitHeight Unit.Vh
        >> slidePanelIn
        >> growPanel

Playback

These functions are precedence functions, so they can operate as a global setting for all groups in the builder chain, or you can set them on a per-group basis which overrides any global setting for that group.

Keyframe.iterations 3 -- global setting
    >> Keyframe.for "box"
    >> Keyframe.iterations 5 -- overrides global for this group
    >> ... -- other builders
iterations : Int -> EngineBuilder -> EngineBuilder

Set how many times an animation should repeat.

loopForever : EngineBuilder -> EngineBuilder

Make an animation loop infinitely.

alternate : EngineBuilder -> EngineBuilder

Make an animation alternate direction on each iteration.

Only has a visible effect when the animation runs more than once, so calling it when iterations is unset or 1 automatically bumps iterations to 2.

An explicit iterations count (or loopForever) set before or after alternate is preserved.

Timing

📖 See Timing for details.

delay : Int -> EngineBuilder -> EngineBuilder

Set the global delay for all animations in this builder.

introAnim : EngineBuilder -> EngineBuilder
introAnim =
    delay 500
        >> fadeInHeader
        >> slideInSidebar
        >> fadeInContent
duration : Int -> EngineBuilder -> EngineBuilder

Set the global duration for all animations in this builder.

introAnim : EngineBuilder -> EngineBuilder
introAnim =
    duration 500
        >> fadeInHeader
        >> slideInSidebar
        >> fadeInContent
speed : Float -> EngineBuilder -> EngineBuilder

Set the global speed for all animations in this builder.

introAnim : EngineBuilder -> EngineBuilder
introAnim =
    speed 300
        >> slideDownHeader
        >> slideInSidebar
        >> slideUpContent

Easing

📖 See Easing for details.

easing : Easing -> EngineBuilder -> EngineBuilder

Set the global easing function.

heroEntrance : EngineBuilder -> EngineBuilder
heroEntrance =
    easing EaseInOut
        >> fadeInHeroTitle
        >> slideInHeroArtwork
        >> revealPrimaryCta

Spring

spring : Spring -> EngineBuilder -> EngineBuilder

Set the global spring.

draggableCardSettle : EngineBuilder -> EngineBuilder
draggableCardSettle =
    spring Spring.wobbly
        >> settleCardPosition
        >> settleCardShadow

Animation Control

📖 See Controlling Animations for details.

stop : AnimGroupName -> AnimState -> AnimState

Stop a running animation by instantly jumping to its end state.

import Anim.Engine.Keyframe as Keyframe


Keyframe.stop "animGroup" model.animState
reset : AnimGroupName -> AnimState -> AnimState

Reset an animation by instantly jumping back to its start state.

import Anim.Engine.Keyframe as Keyframe


Keyframe.reset "animGroup" model.animState
AnimGroupName
-> (AnimMsg -> msg)
-> AnimState
-> ( AnimState, Cmd msg )

Restart an animation from the beginning.

import Anim.Engine.Keyframe as Keyframe


let
    ( newState, cmd ) =
        Keyframe.restart "boxAnim" GotAnimMsg model.animState
in
( { model | animState = newState }, cmd )
AnimGroupName
-> (AnimMsg -> msg)
-> AnimState
-> ( AnimState, Cmd msg )

Pause a running animation.

import Anim.Engine.Keyframe as Keyframe


let
    ( newState, cmd ) =
        Keyframe.pause "boxAnim" GotAnimMsg model.animState
in
( { model | animState = newState }, cmd )
AnimGroupName
-> (AnimMsg -> msg)
-> AnimState
-> ( AnimState, Cmd msg )

Resume a paused animation.

import Anim.Engine.Keyframe as Keyframe


let
    ( newState, cmd ) =
        Keyframe.resume "boxAnim" GotAnimMsg model.animState
in
( { model | animState = newState }, cmd )

Discrete Properties

📖 See Discrete Properties for details.

discreteEntry : String -> String -> EngineBuilder -> EngineBuilder

Add a discrete CSS property for entry animations.

The value is applied at every step of the animation, ensuring the element is immediately in the target state when the animation starts. The browser already knows the element's pre-animation state from its own CSS.

This function is a precedence function, so it can operate as a global setting for all groups in the builder chain, or you can set it on a per-group basis which overrides any global setting for that group.

import Anim.Engine.Keyframe as Keyframe
import Anim.Property.Opacity as Opacity


Keyframe.animate model.animState <|
    Keyframe.discreteEntry "display" "block"
        >> Keyframe.discreteEntry "pointer-events" "auto"
        >> Keyframe.for "box"
        >> Opacity.begin
        >> Opacity.to 1
        >> Opacity.end
discreteExit : String -> String -> String -> EngineBuilder -> EngineBuilder

Add a discrete CSS property for exit animations.

Exit animations need to hold their initial state until the very end of the animation, at which point they flip to the final state. Therefore you need to set both entry and exit values for the property.

This function is a precedence function, so it can operate as a global setting for all groups in the builder chain, or you can set it on a per-group basis which overrides any global setting for that group.

Use when an element is disappearing (e.g., going from display: block to display: none):

import Anim.Engine.Keyframe as Keyframe
import Anim.Property.Opacity as Opacity


Keyframe.animate model.animState <|
    Keyframe.discreteExit "display" "block" "none"
        >> Keyframe.for "box"
        >> Opacity.begin
        >> Opacity.to 0
        >> Opacity.end

Transform Order

📖 See Transform Ordering for details.

transformOrder : List TransformProperty -> EngineBuilder -> EngineBuilder

Set the transform order.

The transform order specifies how translate, rotate, skew and scale transforms are combined. Start the list with the transform to apply first.

This is a precedence function, so it can operate as a global setting for all groups in the builder chain, or you can set it on a per-group basis which overrides any global setting for that group.

Any missing transforms are automatically appended in the default order (Translate → Rotate → Skew → Scale).

import Anim.Engine.Keyframe as Keyframe
import Anim.Extra.TransformOrder exposing (TransformProperty(..))


Keyframe.transformOrder [ Scale, Rotate, Translate, Skew ] -- global setting
    >> Keyframe.for "box"
    >> Keyframe.transformOrder [ Rotate, Translate ] -- overrides global for this group
    >> ... -- other builders

State Queries

📖 See State Queries for details.

anyRunning : AnimState -> Maybe Bool

Check if any animations are currently running.

Returns Nothing if there are no animations.

isRunning : AnimGroupName -> AnimState -> Maybe Bool

Check if a specific animation group is currently running.

Returns Nothing if there are no animations for the group.

allComplete : AnimState -> Maybe Bool

Check if all animations are complete.

Returns Nothing if there are no animations.

isComplete : AnimGroupName -> AnimState -> Maybe Bool

Check if a specific animation group has completed.

Returns Nothing if there are no animations for the group.

isCancelled : AnimGroupName -> AnimState -> Maybe Bool

Check if a specific animation group was cancelled.

Returns Nothing if there are no animations for the group.

Property Queries

📖 See Property Queries and Properties for details.

Custom Properties

getPropertyEnd : AnimGroupName -> String -> AnimState -> Maybe Float

Get the end value of a custom property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom property.

AnimGroupName
-> String
-> AnimState
-> Maybe
{ start : Maybe Float
, end : Float
}

Get the custom property range (start and end) of an element being animated.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom property.

getPropertyStart : AnimGroupName -> String -> AnimState -> Maybe Float

Get the start value of a custom property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom property.

Returns Just 0 if no explicit start value was set, which is the default when no start value is set.

Custom Color Properties

getColorPropertyEnd : AnimGroupName -> String -> AnimState -> Maybe Color

Get the end value of a custom color property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom color property.

AnimGroupName
-> String
-> AnimState
-> Maybe
{ start : Maybe Color
, end : Color
}

Get the custom color property range (start and end) of an element being animated.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom color property.

getColorPropertyStart : AnimGroupName -> String -> AnimState -> Maybe Color

Get the start value of a custom color property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom color property.

Returns transparent white (rgba 255 255 255 0) if no explicit start value was set, which is the default when no start value is set.

Opacity

getOpacityStart : AnimGroupName -> AnimState -> Maybe Float

Get the start opacity of an element being animated.

Returns Nothing if the element has no opacity animation.

Returns Just 1.0 (fully opaque) if no explicit start value was set, which is the default when no start value is set.

getOpacityEnd : AnimGroupName -> AnimState -> Maybe Float

Get the end opacity of an element being animated.

Returns Nothing if the element has no opacity animation.

AnimGroupName
-> AnimState
-> Maybe
{ start : Maybe Float
, end : Float
}

Get the opacity range (start and end) of an element being animated.

Returns Nothing if the element has no opacity animation.

Perspective Origin

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
}

Get the start perspective origin of an element being animated.

Returns Nothing if the element has no perspective origin animation.

Returns Just { x = 50, y = 50 } if no explicit start value was set, which is the default when no start value is set.

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
}

Get the end perspective origin of an element being animated.

Returns Nothing if the element has no perspective origin animation.

AnimGroupName
-> AnimState
-> Maybe
{ start :
Maybe
{ x : Float
, y : Float
}
, end :
{ x : Float
, y : Float
}
}

Get the perspective origin range (start and end) of an element being animated.

Returns Nothing if the element has no perspective origin animation.

Rotate

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
, z : Float
}

Get the start rotation of an element being animated.

Returns Nothing if the element has no rotate animation.

Returns Just { x = 0, y = 0, z = 0 } if no explicit start value was set, which is the default when no start value is set.

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
, z : Float
}

Get the end rotation of an element being animated.

Returns Nothing if the element has no rotate animation.

AnimGroupName
-> AnimState
-> Maybe
{ start :
Maybe
{ x : Float
, y : Float
, z : Float
}
, end :
{ x : Float
, y : Float
, z : Float
}
}

Get the rotate range (start and end) of an element being animated.

Returns Nothing if the element has no rotate animation.

Scale

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
, z : Float
}

Get the start scale of an element being animated.

Returns Nothing if the element has no scale animation.

Returns Just { x = 1, y = 1, z = 1 } if no explicit start value was set, which is the default when no start value is set.

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
, z : Float
}

Get the end scale of an element being animated.

Returns Nothing if the element has no scale animation.

AnimGroupName
-> AnimState
-> Maybe
{ start :
Maybe
{ x : Float
, y : Float
, z : Float
}
, end :
{ x : Float
, y : Float
, z : Float
}
}

Get the scale range (start and end) of an element being animated.

Returns Nothing if the element has no scale animation.

Size

AnimGroupName
-> AnimState
-> Maybe
{ width : Float
, height : Float
}

Get the start size of an element being animated.

Returns Nothing if the element has no size animation.

Returns Just { width = 0, height = 0 } if no explicit start value was set, which is the default when no start value is set.

AnimGroupName
-> AnimState
-> Maybe
{ width : Float
, height : Float
}

Get the end size of an element being animated.

Returns Nothing if the element has no size animation.

AnimGroupName
-> AnimState
-> Maybe
{ start :
Maybe
{ width : Float
, height : Float
}
, end :
{ width : Float
, height : Float
}
}

Get the size range (start and end) of an element being animated.

Returns Nothing if the element has no size animation.

Skew

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
}

Get the end skew of an element being animated.

Returns Nothing if the element has no skew animation.

AnimGroupName
-> AnimState
-> Maybe
{ start :
Maybe
{ x : Float
, y : Float
}
, end :
{ x : Float
, y : Float
}
}

Get the skew range (start and end) of an element being animated.

Returns Nothing if the element has no skew animation.

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
}

Get the start skew of an element being animated.

Returns Nothing if the element has no skew animation.

Returns Just { x = 0, y = 0 } if no explicit start value was set, which is the default when no start value is set.

Translate

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
, z : Float
}

Get the start translate of an element being animated.

Returns Nothing if the element has no translate animation.

Returns Just { x = 0, y = 0, z = 0 } if no explicit start value was set, which is the default when no start value is set.

AnimGroupName
-> AnimState
-> Maybe
{ x : Float
, y : Float
, z : Float
}

Get the end translate of an element being animated.

Returns Nothing if the element has no translate animation.

AnimGroupName
-> AnimState
-> Maybe
{ start :
Maybe
{ x : Float
, y : Float
, z : Float
}
, end :
{ x : Float
, y : Float
, z : Float
}
}

Get the translate range (start and end) of an element being animated.

Returns Nothing if the element has no translate animation.

Modules

About this package serverReroutesreroutes.json
Pages and docs rendering from package.elm-lang.org, © 2012-2020 Evan Czaplicki. © 2026 Lamdera