Cuttlefish Docs
  • English

    • spz-animation

    When to use

    spz-animation applies a CSS class to one or more target elements in response to various triggers — viewport visibility, scroll, click, mousemove, or manual invocation.

    Use it when you need to:

    • Play entrance animations when elements scroll into view
    • Track scroll position via CSS variables for scroll-linked effects
    • Trigger animations on click or hover
    • Coordinate animation across multiple targets with ordering

    Supported layout

    • logic

    Example

    Fade in on scroll into view

    <spz-animation
  layout="logic"
  trigger="visible"
  target=".card"
  animation-class="fade-in"
  once>
</spz-animation>

    Scroll-linked CSS variable

    <spz-animation
  layout="logic"
  trigger="scroll"
  target="#parallax"
  animation-class="scroll-active">
</spz-animation>

    The target element receives the CSS variable --spzanim-scroll-rect-top which you can use in CSS to drive scroll-linked effects.

    Click trigger

    <spz-animation
  layout="logic"
  trigger="click"
  target="#ripple"
  animation-class="ripple-active"
  event-root="#button-area">
</spz-animation>

    Manual trigger

    <spz-animation
  id="my-anim"
  layout="logic"
  trigger="manual"
  target=".box"
  animation-class="highlight">
</spz-animation>
<button @tap="my-anim.run">Run animation</button>

    Ordered entrance

    <spz-animation
  layout="logic"
  trigger="visible"
  target=".list-item"
  animation-class="slide-up"
  set-order
  once>
</spz-animation>

    Each .list-item receives the CSS variable --spzanim-order (0, 1, 2, ...) which you can use in animation-delay for staggered effects.

    Attributes

    AttributeDescriptionTypeRequired
    triggerComma-separated trigger types: visible, manual, scroll, click, mousemovestringNo
    targetComma-separated CSS selectors for target elementsstringNo
    animation-classCSS class to apply when the animation is triggeredstringNo
    new-targetWhen present, dynamically creates a new target elementbooleanNo
    new-target-rootCSS selector for the root element to append the new target tostringNo
    onceWhen present, the animation runs only once (for visible trigger)booleanNo
    ignore-initialWhen present, ignores the initial intersection check (for visible trigger)booleanNo
    set-orderWhen present, sets an order index on each target via --spzanim-orderbooleanNo
    order-rootCSS selector for the root element when calculating orderstringNo
    style-variablesJSON string of CSS variables to set on targetsstringNo
    event-rootCSS selector for the event listener root (for click / mousemove triggers)stringNo

    CSS variables

    The component sets the following CSS variables on target elements, depending on the trigger type:

    VariableTriggerDescription
    --spzanim-ordervisible (with set-order)Order index of the target (0, 1, 2, ...)
    --spzanim-scroll-rect-topscrollScroll position of the target relative to viewport
    --spzanim-click-xclickClick X coordinate relative to viewport
    --spzanim-click-yclickClick Y coordinate relative to viewport
    --spzanim-mousemove-xmousemoveMouse X coordinate relative to viewport
    --spzanim-mousemove-ymousemoveMouse Y coordinate relative to viewport

    Actions

    run

    Manually trigger the animation. Typically used with trigger="manual".

    Example:

    <button @tap="my-anim.run">Trigger</button>

    Events

    EventDescription
    finishFired when the animation ends (via animationend listener on targets)

    Notes

    • The animation-class is added on trigger and removed when the animation ends (unless once is set with visible).
    • style-variables supports element references like ${elementId} and $(selector) for dynamic value computation.