Guide

HTML / CDN and loading options

Understand package imports, script tags, CDN delivery, window.Ticker and the optional browser registry.

Ticker has two loading setups. Both run in the browser and return the same controller; choose one for each integration.

Loading terms

Term	Meaning	How it fits
Package / ESM	Install with npm, pnpm, yarn or bun; import `ticker` in your application.	Load `@samline/ticker/style.css` once. Use your existing build tool. CommonJS exports are also available.
HTML / CDN	Load the standalone JavaScript with a `<script>` tag and CSS with `<link>`.	Initialize through `window.Ticker.ticker(...)`; no bundler is needed.
CDN	A server that delivers the package files.	jsDelivr or unpkg can deliver the HTML script and stylesheet. Self-hosting those same files works too.
Global / IIFE	The script format and the object it exposes.	The standalone file `dist/browser/global.global.js` installs `window.Ticker`. It is the HTML / CDN build, not another integration mode.
Browser registry	Optional ID-based ownership through `newTicker()` and registry helpers.	Available as an imported `browser` object or through `window.Ticker`. The `/browser` module is not the standalone script.

Start with ticker(target, options) unless you need ID-based lookup. Do not load both the imported module and the standalone script for the same ticker. Choose controller ownership or the declarative page manager independently of how the files are delivered.

HTML / CDN setup

Save these three files in the same folder. The HTML loads package CSS and the standalone script before main.js; style.css contains only the example layout.

HTML

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Ticker news</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@samline/ticker@2.1.0/dist/style.css">
    <link rel="stylesheet" href="./style.css">
  </head>
  <body>
    <div id="news">
      <a href="/one">First story</a>
      <a href="/two">Second story</a>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/@samline/ticker@2.1.0/dist/browser/global.global.js"></script>
    <script type="module" src="./main.js"></script>
  </body>
</html>

CSS

style.css

.ticker-track,
.ticker-content,
#news {
  gap: 1.5rem;
}

#news {
display: flex;
width: max-content;
}

#news a {
flex-shrink: 0;
}

JavaScript

main.js

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

news?.update({ duration: 30 })
window.addEventListener('pagehide', event => {
if (!event.persisted) news?.destroy()
})

Use matching pinned versions of both assets. To self-host, copy the package stylesheet and standalone script from the installed package’s dist/ directory to your own server and update the URLs. A CDN is optional; the initialization API stays window.Ticker.ticker().

Keep loading ordered: the standalone script must run before the initializer. Do not add async to it or pair a deferred external script with an inline initializer that runs immediately.

Optional registry

Use window.Ticker.newTicker({ id: 'news', options }) only when you want a registration addressable by id. Clean it up with window.Ticker.destroyTicker('news'). Calling window.Ticker.ticker() creates an unregistered controller, so clean that up with its own destroy().

Namespace

Member	Result
`ticker(target, options?)`	Create an unregistered element-scoped controller.
`newTicker({ id, options? })`	Create and register a controller by source element id.
`getTicker(id)`	Read a registered wrapper or `null`.
`getTickers()`	Read a snapshot of all registered wrappers.
`destroyTicker(id)`	Destroy a registration and restore its source.
`destroyTickers()`	Destroy every registration.
`available`	Live object of wrappers keyed by id.

newTicker() returns the same controller shape as ticker(). Reusing an id destroys the previous controller before creating its replacement, so generated wrappers never nest.

Browser module

In Package / ESM, import the same optional registry without installing window.Ticker:

import { browser } from '@samline/ticker/browser'

const news = browser.newTicker({ id: 'news' })
news?.update({ direction: 'right' })
browser.destroyTicker('news')

The ESM/CJS module has no globalThis side effect. Only @samline/ticker/browser/global installs window.Ticker.