Skip to content
samlinePublic

About

An accessible, dependency-free ticker (marquee) for vanilla JavaScript, TypeScript, and plain HTML.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

133 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@samline/ticker

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

Table of contents

Installation

npm install @samline/ticker
pnpm add @samline/ticker
bun add @samline/ticker

Requires Node 20+ when bundling. Runtime target is ES2020.

Import the stylesheet once in your application entrypoint:

import '@samline/ticker/style.css'

Quick start

<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.

HTML / CDN

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.0 with 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.

Capabilities

  • 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.

Seamless loops

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.

Featured items

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 at a glance

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.

Entrypoints

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.

Playback, navigation and responsive motion

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.

Smooth arrow steps

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.

Documentation

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.

Changelog

Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.

AI agent skill

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.md

When working from this repository, copy skills/ticker/SKILL.md instead. Keep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.

License

MIT — LICENSE.md.

About

An accessible, dependency-free ticker (marquee) for vanilla JavaScript, TypeScript, and plain HTML.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages