- Docs
- Configuration
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 items
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.