Getting started

This page walks through installing @samline/ticker, loading its stylesheet, and controlling a working ticker. By the end you will understand both controller-owned and declarative lifecycles.

Choose your setup

• Package / ESM: install with your package manager, import ticker and the stylesheet, then initialize in your application’s client code.
• HTML / CDN: load CSS and the standalone script, then call window.Ticker.ticker(). A CDN delivers the files; serving them yourself uses the same API.

Both return the same controller. “Global” means the window.Ticker object created by the standalone script; the optional /browser registry module is a separate import for ID-based ownership. See how these terms fit together.

Prerequisites

• Node.js 20+ for Package / ESM tooling; HTML / CDN needs no Node.js or build step.
• A package manager — npm, pnpm, yarn or bun — for Package / ESM.
• A browser target of ES2020.

Install

npm install @samline/ticker

pnpm add @samline/ticker

yarn add @samline/ticker

bun add @samline/ticker

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@samline/ticker@2.1.0/dist/style.css" />
<script src="https://cdn.jsdelivr.net/npm/@samline/ticker@2.1.0/dist/browser/global.global.js"></script>

Installed with a package manager? Choose Package / ESM below. Loaded the CDN assets? Choose HTML / CDN. Both use the same source markup and controller API.

First example

<div id="news-ticker">
  <a href="/story/one">First story</a>
  <a href="/story/two">Second story</a>
</div>

import { ticker } from '@samline/ticker'
import '@samline/ticker/style.css'

const news = ticker('#news-ticker', {
  duration: 24,
  direction: 'left',
  pauseOnHover: true,
})

if (!news) throw new Error('Ticker target not found')

news.update({ duration: 32 })
news.refresh()

const news = window.Ticker.ticker('#news-ticker', {
  duration: 24,
  direction: 'left',
  pauseOnHover: true,
})

if (!news) throw new Error('Ticker target not found')

news.update({ duration: 32 })
news.refresh()

What this does:

• Wraps the source content in the required ticker structure.
• Measures it and creates enough visual clones to fill the viewport.
• Keeps clones out of the accessibility tree and tab order by default.
• Rebuilds after responsive size changes.
• Returns null without changing the DOM if the selector is missing.

Controller lifecycle

Destroy the controller when the view that created it is removed:

news.destroy()

Declarative markup

When a server or template renders the complete ticker structure, initialize it at page level:

<div data-ticker data-duration="24" data-direction="left" data-pause-on-hover="true">
  <div data-ticker-track>
    <div data-ticker-content>...</div>
  </div>
</div>

import { mount, unmount } from '@samline/ticker/vanilla'
import '@samline/ticker/style.css'

mount()
window.addEventListener('pagehide', event => {
  if (!event.persisted) unmount()
})

Use your host framework

See Framework integrations for React, Vue, Svelte, Astro, Shopify and WordPress examples with client setup, accessible playback and cleanup.

What’s next?