An accessible, dependency-free ticker for JavaScript, TypeScript and plain HTML. Enhance existing markup with an owned controller or initialize declarative tickers at page level.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/tickerpnpm add @samline/tickerbun add @samline/tickerRequires Node 20+ when bundling. Runtime target is ES2020.
Import the stylesheet once in your application entrypoint:
import '@samline/ticker/style.css'<div id="news-ticker">
<a href="/one">First story</a>
<a href="/two">Second story</a>
</div>import { ticker } from '@samline/ticker'
import '@samline/ticker/style.css'
const news = ticker('#news-ticker', {
duration: 20,
direction: 'left',
pauseOnHover: true,
})
news?.update({ duration: 30 })
news?.refresh()
news?.destroy()What this does:
- Enhances the existing element and returns an element-scoped controller.
- Measures its content and creates enough visual clones to fill the viewport.
- Preserves fractional widths and horizontal gaps so repeated content aligns at each loop reset.
- Hides repeated content from assistive technology and keyboard navigation by default.
- Reuses visual clones when responsive measurements are unchanged and pauses animation outside the viewport or while the document is hidden.
- Restores the original source element when
destroy()runs.
Choose Package / ESM when installing with npm, pnpm or bun and importing Ticker in your application. Choose HTML / CDN when loading the standalone script in plain HTML, WordPress or Shopify without a bundler. Both use the same controller API. A CDN only delivers the files; you can self-host the same script and stylesheet.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@samline/ticker@4.0.0/dist/style.css" />
<script src="https://cdn.jsdelivr.net/npm/@samline/ticker@4.0.0/dist/browser/ticker.global.js"></script>Pin the version in production. Replace
4.0.0with the version you ship.
The standalone script (an IIFE) exposes window.Ticker. “Global” describes this object, not another loading mode. The optional @samline/ticker/browser registry module is an ESM/CJS import and does not install that object. See loading terms.
<div id="news"><a href="/news">Latest story</a></div>
<script>
const news = window.Ticker.ticker('#news', {
duration: 24,
pauseOnHover: true,
})
news?.update({ duration: 30 })
</script>For optional ID-based ownership, window.Ticker.newTicker({ id, options }) creates a registry entry; destroyTicker(id) removes it. A direct ticker() controller is unregistered and uses its own destroy(). See Registry reference for the complete browser API.
- News, announcement, logo, sponsor, and promotion tickers.
- Progressive enhancement for server-rendered or CMS-owned markup.
- Responsive marquees that remeasure after fonts, layout, or content change.
- Browser-global integrations for WordPress, Shopify, and plain HTML.
- Declarative tickers that are discovered as the DOM changes.
The runtime preserves fractional measurements in both directions. Match item spacing to the horizontal track gap and include any decorative separator at the end of the sequence. See Styling: seamless loops for the CSS pattern.
Keep one original fixed while the remaining sequence passes behind it. Mark a direct item with data-featured; when several are marked, the first in original DOM order wins and the rest move normally. Configure featuredPosition (start, center, end, or axis-specific physical edges). controller.setFeatured(item) replaces it; setFeatured(null) clears it; controller.featured exposes the original. Featured items are excluded from clones and repeat distance, retain identity/focus and return to their original position on release/destroy.
Featured items require version 2.4.0 or later and matching JavaScript and stylesheet. See featured configuration and the gallery for the complete contract and runnable examples.
| API | Purpose |
|---|---|
ticker() |
Controller factory |
update() · refresh() · destroy() |
Controller lifecycle |
mount() · refresh() · unmount() |
Declarative lifecycle |
newTicker() and registry helpers |
Browser registry |
featured and setFeatured() |
Featured |
TickerOptions |
Configuration |
| Defaults, state factories, and validators | Core utilities |
| TypeScript reference | Types |
The controller exposes element, source, state, and an immutable options snapshot. Playback, navigation, events and viewport rules are documented in the controller reference. update() and instance refresh() are chainable; destroy() owns teardown and restoration.
See the complete API reference.
| Entrypoint | When to use |
|---|---|
@samline/ticker |
Main API, browser singleton, types, defaults, and validators. |
@samline/ticker/vanilla |
ticker() plus declarative page lifecycle helpers. |
@samline/ticker/browser |
ESM/CJS browser registry without a global side effect. |
@samline/ticker/browser/global |
Pre-bundled IIFE that installs window.Ticker. |
@samline/ticker/core |
Types, defaults, state factories, and validation helpers. |
@samline/ticker/style.css |
Required layout, animation, and reduced-motion styles. |
The main entrypoint also exports browser, the same registry singleton used by the browser module, without installing window.Ticker. See Browser integration.
const news = ticker('#news', {
speed: 40, // CSS pixels per second; takes precedence over duration.
direction: 'auto', // Inherited LTR moves left; inherited RTL moves right.
autoplay: false,
navigation: true,
responsive: [{ query: '(width < 48rem)', options: { speed: 24 } }],
})
news?.play()
news?.pause()
news?.scrollBy(120) // Instant logical distance; wraps and leaves playback paused.
const unsubscribe = news?.on('playback', state => console.log(state.playing, state.reasons))direction also accepts physical left/right and vertical up/down. Give vertical wrappers an explicit height. pauseOnFocus defaults to true; manual pause survives environmental and breakpoint changes. play() respects reduced motion, document visibility and viewport intersection. Attach application-owned native buttons and a labelled range using connectControls({ previous, next, rail }); navigation: true enables touch/mouse dragging without blocking perpendicular page scroll. Set resumeAfterDrag: true to restore prior playback intent on release; a manual pause remains paused and hover/focus pauses still apply. Responsive rules use viewport media queries in array order over the current base configuration. The same typed controller is returned by Package / ESM and HTML / CDN factories, with equivalent declarative data attributes. Compare enabled/disabled resumption in the drag example; its control calls update({ resumeAfterDrag }) without changing playback intent.
Content stays application-owned: add or remove original nodes through source, then call refresh(). Use speed to keep a dynamic feed steady as it grows or shrinks; an empty feed can be repopulated and refreshed.
See configuration for normalization, RTL and rule precedence, and controller contracts for events, keyboard controls and cleanup.
Create native #previous and #next buttons beside the Quick start source.
This is an alternative setup; a second ticker() call for the same source returns the existing controller.
import { ticker } from '@samline/ticker'
import '@samline/ticker/style.css'
const strip = ticker('#news-ticker', { navigation: true, autoplay: true })
const disconnect = strip?.connectControls({
previous: document.querySelector<HTMLButtonElement>('#previous')!,
next: document.querySelector<HTMLButtonElement>('#next')!,
itemsPerStep: 1,
behavior: 'smooth',
duration: 300,
preservePlayback: true,
resumeDelay: 1500,
})Arrows reveal one incoming item by default, including a partially hidden item. Set
itemsPerStep: 2 to request two; movement stops before the first incoming item
would leave the opposite edge. Set CSS scroll-padding on the wrapper to reserve
space for edge fades or overlays. A positive pixel step overrides item stepping.
Rapid clicks in the same direction add steps to the pending destination. Changing
direction discards that destination and steps from the currently visible position.
Each click retargets the smooth movement without jumping; duration runs from the
latest click. Rail arrow keys follow the same policy.
Since 2.6.0, inertia: true (or data-inertia="true") lets a released touch or mouse
drag glide to a stop. inertiaDeceleration (default 1800 px/s²) and
inertiaMaxVelocity (default 2500 px/s) tune it; slow releases, cancelled
gestures and reduced motion do not glide, and resumeAfterDrag resumes autoplay
when the glide ends.
ticker('#feed', { navigation: true, inertia: true, resumeAfterDrag: true })Use your existing controller instead of resuming on every navigate event.
preservePlayback retains manual pause as well as autoplay. Since 2.5.0, the
resumeDelay option adds a reading pause in milliseconds after seeking (default
0, requires preservePlayback: true). Each new command replaces that wait;
explicit playback commands cancel it. Item arrows default
to smooth movement on both axes; pixel seeks and explicit pixel steps remain instant
by default. Navigation pauses playback unless preservation is enabled. Reduced motion always seeks instantly.
See the controller documentation for cancellation and navigationSource events.
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files for both loading modes.
| Guide | What it covers |
|---|---|
| Installation | Installation, first ticker, ownership, and lifecycle. |
| Configuration | Every option, default, normalization rule, and data attribute. |
| Browser integration | Optional ID-based ownership for either loading setup. |
| Entrypoints | Root, Vanilla, core, browser, global, and CSS exports. |
| Styling | Required stylesheet, DOM contract, classes, and CSS variables. |
| Accessibility | Clone behavior, reduced motion, and interactive content. |
| Core utilities | Defaults, state factories, validators, and advanced contracts. |
| TypeScript | Exported TypeScript types and their roles. |
| API reference | Public functions and controller methods. |
| Recipes | Task-oriented integration and lifecycle recipes. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
The public Ticker skill teaches an agent how to choose a Ticker integration, load CSS, manage controllers, preserve accessible motion and avoid nonexistent APIs. It is self-contained and describes v3.0.0; agents must verify their installed version.
The maintained repository source and website download are the same file.
Download SKILL.md into a ticker/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/ticker
curl --fail --location https://samline.github.io/ticker/skills/ticker/SKILL.md \
--output .agents/skills/ticker/SKILL.mdWhen working from this repository, copy skills/ticker/SKILL.md instead. Keep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.