API reference

Configuration

Every TickerOptions field, default, normalization rule, data attribute, and runtime effect.

interface TickerOptions {
  duration?: number
  featuredPosition?: TickerFeaturedPosition // Since 2.4.0
  speed?: number
  direction?: 'left' | 'right' | 'up' | 'down' | 'auto'
  autoplay?: boolean
  pauseOnHover?: boolean
  pauseOnFocus?: boolean
  navigation?: boolean
  resumeAfterDrag?: boolean
  inertia?: boolean
  inertiaDeceleration?: number
  inertiaMaxVelocity?: number
  responsive?: readonly TickerResponsiveRule[]
  interactiveClones?: boolean
  class?: string
}

Options table

Option Default Normalization and behavior
duration 20 Positive finite seconds per cycle; invalid values fall back to 20.
featuredPosition 'center' Since 2.4.0: fixed original alignment; invalid values become center. See Featured items.
speed 0 Positive finite CSS pixels per second overrides duration. Invalid, zero or negative values disable speed mode.
direction 'left' Exact left, right, up, down, auto; invalid values become left.
autoplay true Only false starts paused. play() and pause() change intent independently of automatic pause causes.
pauseOnHover false Only true enables pointer hover pause.
pauseOnFocus true Only false disables focus pause. Focus moving between descendants never resumes playback.
resumeAfterDrag false Only true restores pre-drag playback intent on release; existing manual and environmental pauses remain effective.
inertia false Only true continues a released drag with momentum.
inertiaDeceleration 1800 Positive momentum deceleration in CSS px/s²; invalid values use the default.
inertiaMaxVelocity 2500 Positive release-velocity limit in CSS px/s; invalid values use the default.
navigation false Only true enables pointer dragging and manual navigation in reduced motion.
responsive [] Ordered viewport media-query rules; see below.
interactiveClones false Only true enables interactive repeated copies.
class '' Whitespace-separated wrapper classes; excludes reserved ticker-wrapper.

duration

Duration is seconds per one-content-and-gap cycle. Larger values move more slowly.

ticker('#headlines', { duration: 30 })

Zero, negative, NaN, and infinite values fall back to 20. Declarative strings are parsed with parseFloat.

direction

ticker('#headlines', { direction: 'right' })

left and right remain physical directions regardless of dir. up and down select the vertical axis. auto moves left in LTR and right in RTL, using the wrapper’s inherited writing direction at measurement time. Call refresh() after changing an ancestor’s dir without resizing.

Vertical and writing direction

Give vertical wrappers a definite visible height. The runtime measures the full original height plus computed row-gap; different item heights and fractional pixels are supported. Horizontal motion uses width plus column-gap. Match gaps inside the original sequence and between its copies.

.news-column .ticker-wrapper {
  height: 12rem;
}
.news-column .ticker-track,
.news-column .ticker-content {
  gap: 0.75rem;
}
ticker('#vertical-news', { direction: 'up', speed: 30 })

Content keeps its writing direction, Unicode characters and bidi ordering. The repeating groups are laid out on a physical axis while the contents of RTL groups retain RTL layout. Do not reverse strings or Arabic/Hebrew characters. Explicit left/right retain their existing meanings. scrollBy(positive) and Next follow reading order: leftward travel for LTR, rightward for RTL; vertical Next travels upward. Previous reverses that logical movement. The position rail uses the same logical distance, with left/right keyboard arrows following writing direction and up/down following the vertical axis. See navigation.

speed

A positive finite speed in CSS pixels per second takes precedence over duration. The runtime derives seconds per cycle as (content extent + axis gap) / speed. Resize, fonts, loaded images and refresh() remeasure this exact fractional distance. Changing speed or duration preserves pixel position; CSS linear animation uses elapsed time rather than frame count.

const news = ticker('#news', { speed: 40, duration: 20 })
news?.update({ speed: 0 }) // Return to 20 seconds per cycle.

autoplay, pauseOnFocus and playback

Playback starts requested by default. Use autoplay: false to start paused and pause() / play() for persistent intent. Focus pause is enabled by default in 2.1; disabling it requires pauseOnFocus: false. Hover, focus, hidden document, viewport intersection and reduced motion compose; clearing one cause never clears another. play() respects all environmental causes. See controller state.

responsive

TickerResponsiveRule contains query: string and options: Omit<TickerOptions, 'responsive' | 'class'>. Rules use viewport media queries via matchMedia, rather than container width. All matching rules merge in array order after base options. The last matching field wins. update() changes the base, then rules are reapplied; leaving a rule restores the current base. Replacing responsive replaces the complete rule list and removes old listeners. options reports the base snapshot; state reports actual playback and measured duration.

const news = ticker('#news', {
  speed: 45,
  responsive: [
    { query: '(width < 48rem)', options: { speed: 24 } },
    { query: '(width < 30rem)', options: { autoplay: false } },
  ],
})
news?.update({ speed: 50 }) // Matching rules still override this base.

A rule’s autoplay changes requested playback until an explicit play() or pause() takes ownership. An explicit pause survives every rule transition. Explicit update({ autoplay }) releases that manual override. Reduced motion always prevents automatic playback. Changes on the same axis preserve pixel position modulo the new cycle; changing axis resets to its beginning. Original nodes remain intact; clones are rebuilt only for changed geometry/configuration or explicit refresh. Destroy removes all media listeners.

pauseOnHover

ticker('#offers', { pauseOnHover: true })

Pauses the track while the wrapper is hovered. This is a pointer convenience; provide explicit page controls when essential content must be stoppable.

interactiveClones

The default false hides clones from assistive technology, removes keyboard interaction, and disables pointer events. true skips those protections:

ticker('#products', { interactiveClones: true })

Read Accessibility and motion before enabling it.

class

const partners = ticker('#partners', { class: 'partners theme-light' })
partners?.update({ class: 'partners theme-dark' })

Updates replace only prior option-owned tokens. Independently added application classes remain. ticker-wrapper is runtime-owned and filtered from this option.

Partial updates and snapshots

update() shallow-merges fields with current normalized options, so omitted values stay unchanged. instance.options returns a new read-only snapshot; mutating it cannot update the ticker.

const partners = ticker('#partners', { duration: 18, pauseOnHover: true })
partners?.update({ direction: 'right' })

Declarative attributes

Attribute Accepted value Default
data-duration Positive numeric text, parsed with parseFloat. 20
data-featured-position Since 2.4.0: start, center, end, left, right, top, bottom. center
data-speed Positive finite numeric text, parsed with Number. 0
data-direction left, right, up, down, auto. left
data-autoplay Exact string false starts paused. true
data-pause-on-focus Exact string false disables focus pause. true
data-pause-on-hover Exact string true. false
data-resume-after-drag Exact string true; restores pre-drag playback intent. false
data-navigation Exact string true. false
data-inertia Exact string true; momentum after a released drag. false
data-inertia-deceleration Positive number, CSS px/s². 1800
data-inertia-max-velocity Positive number, CSS px/s. 2500
data-interactive-clones Exact string true. false
data-responsive JSON array of { query, options } rules; malformed input becomes []. []
<div
  class="ticker-wrapper"
  data-ticker
  data-autoplay="false"
  data-navigation="true"
  data-speed="40"
  data-direction="auto"
  data-responsive='[{"query":"(width < 48rem)","options":{"speed":24}}]'
>
  <div class="ticker-track"><div class="ticker-content">Latest news</div></div>
</div>

Use mount() for declarative discovery or adopt the wrapper with ticker(wrapper) to obtain controls/events. Browser/CDN controllers provide the same API. Do not create competing controllers for a wrapper.

Runtime outputs

The runtime owns data-ready (measured), data-active (viewport), data-playing (effective playback including focus/hover/manual pause), data-axis, data-motion-direction, data-writing-direction, --ticker-duration, --ticker-distance and --ticker-position. Applications query state and subscribe to events instead of editing these outputs. The CSS variables use seconds and CSS pixels. See styling.

Defaults export

DEFAULT_OPTIONS retains the original four fields (duration, direction, pauseOnHover, interactiveClones) for compatibility. Controller normalization also supplies speed 0, autoplay true, pauseOnFocus true, navigation false, resumeAfterDrag false, responsive [] and class ”. See Core utilities.

Featured support requires 2.4.0 or later and matching JavaScript and stylesheet.

Mark one direct item of the original sequence with data-featured. Ticker moves that original into a fixed .ticker-featured layer inside the wrapper. It never clones the selected original, leaves no moving gap, and excludes it from the repeat distance and item navigation. Other items pass behind it. This works with enhanced sources and explicit track/content markup.

<div id="partners" data-featured-position="center">
  <span class="brand">Partner A</span>
  <span class="brand" data-featured>Main brand</span>
  <span class="brand">Partner B</span>
</div>
import { ticker } from '@samline/ticker'
import '@samline/ticker/style.css'

const partners = ticker('#partners', { featuredPosition: 'center' })

featuredPosition defaults to center, accepts responsive overrides, and can be changed with update(). data-featured-position is also read on enhanced sources and declarative wrappers; an explicit JavaScript option takes precedence.

Value Horizontal Vertical
start Left in LTR; right in RTL Top
center Center Center
end Right in LTR; left in RTL Bottom
left, right Physical edge Center
top, bottom Center Physical edge

Invalid positions normalize to center. Motion direction does not reverse the featured position. TickerFeaturedPosition describes the accepted values.

There is at most one featured item. If several direct originals have data-featured, the first in original DOM order wins, including on refresh. Other marked items move and clone normally. Nested markers are ignored. Changing markers requires refresh(); no attribute observer is installed.

setFeatured(element) selects a direct original explicitly, replacing the current selection. setFeatured(null) clears it and suppresses authored markers for the rest of that controller’s lifetime. An explicit selection remains authoritative on refresh. A foreign element, nested descendant or generated clone throws RangeError without changing the selection. See the controller reference.

Style items through classes scoped to an application-owned ancestor outside the moving source: the featured node no longer matches selectors such as #partners > .brand while fixed. The application owns background, border and padding; use an opaque surface when moving content must not show through it. Keep the featured item small enough to leave a readable area for other content. Oversized content cannot be guaranteed to fit beside an overlay.

Focus pauses still apply. Keyboard focus reveals original content in an uncovered segment beside the featured item; item steps use the largest uncovered segment and honor scroll padding. The featured layer receives pointer actions normally and does not initiate ticker dragging. For selection menus, let the application own selection semantics (aria-pressed for category buttons or aria-current for a real current-page link), and keep an accessible pause control.

A featured-only sequence remains visible but not ready and clone-free; adding moving content and refreshing recovers normal playback. Removing the featured node and refreshing clears the overlay without resurrecting it. Destruction restores a retained original to its comment-marked position and removes the layer. The operation preserves requested playback and native element identity/listeners, and restores focus when moving the focused original.

Try the selected-category example and centered-logo example. Copied files pin the prepared release.