JavaScript API

Loading it

Three files, in order, and only the first is required. deck.js defines the global and the core components. deck-extras.js adds the carousel, drawer, mega menu, copy button, QR encoder and the rest. deck-adapters.js is the bridge to optional third-party libraries and does nothing at all when none of them are present.

<script src="/assets/deck/deck.js" defer></script>
<script src="/assets/deck/deck-extras.js" defer></script>
<script src="/assets/deck/deck-adapters.js" defer></script>

<!-- or all three in one request -->
<script src="/assets/deck/deck.bundle.min.js" defer></script>

Each of the optional two extends Deck.init rather than replacing it, so load order matters and the extras must come after the core. Loading extras without the core logs a warning and stops rather than throwing. Deck is exposed on window, on globalThis, and as a CommonJS export, so it is reachable whether it was loaded as a classic script, a module, or through a bundler.

deck-icons.svg is expected to sit beside deck.js and is found automatically, because the URL is resolved against the script tag's own src at execution time. If your build puts them in different places, set data-deck-icons on the tag.

The data attributes

This is how most people will use the JavaScript: by not writing any. Add an attribute in the markup and Deck.init() wires it on load. There are 15 of them.

<button class="btn btn-icon btn-ghost" data-deck-theme aria-label="Switch theme">
  <svg class="icon"><use href="../../assets/deck/deck-icons.svg#moon"></use></svg>
</button>

Attributes Deck sets on itself

These turn up in dev tools and look like something you were meant to write. They are not: they are the once-guards that make Deck.init() safe to call repeatedly over the same subtree.

Core methods

On window.Deck, from deck.js. Available on every page that loads Deck at all.

const res = await fetch('/rows?page=2');
list.insertAdjacentHTML('beforeend', await res.text());
Deck.init(list);   // only the new rows get wired

Deck.toast('Order #1042 shipped');

Deck.toast({
  kind: 'warn',
  title: 'Project archived',
  text: 'You can still restore it from the archive.',
  duration: 8000,
  actions: [{ label: 'Undo', onClick: restore }]
});

// The handle is the point: one toast, two states
const t = Deck.toast({ kind: 'loading', title: 'Submitting…', duration: 0 });
try {
  await save();
  t.update({ kind: 'good', title: 'Submitted', duration: 4000 });
} catch (err) {
  t.update({ kind: 'bad', title: 'Could not submit', text: err.message, duration: 0 });
}

Deck.toasts.max = 5;
window.addEventListener('beforeunload', () => Deck.toasts.clear());

Deck.theme();          // 'auto', 'light' or 'dark'
Deck.theme('dark');

// A button with data-deck-theme does this for you, with no code at all

// Live preview from a slider
range.addEventListener('input', () => Deck.hue(range.value));

Deck.dir('rtl');
document.querySelectorAll('.mirror-rtl').length;  // glyphs that flip with it

const { months, weekStart, long } = Deck.locale('fr-FR');
months[0];              // 'janvier'
weekStart;              // 1
long.format(new Date());

Deck.transition(() => row.remove());

await Deck.transition(() => {
  list.prepend(newRow);
}, { direction: 'forward' }).finished;
newRow.focus();

await Deck.play(field, 'shake');
field.focus();

Deck.play(card, 'flash-good');

trigger.addEventListener('click', () => {
  const open = Deck.toggle(panel);
  trigger.setAttribute('aria-expanded', String(open));
});

Deck.flip(card);
Deck.flip(card, false);   // back to the front, whatever it was showing

Deck.advance(document.querySelector('.stack-depth'));

Deck.face(cube, 'right');

if (!Deck.reduced()) {
  confetti();
}

Extras and adapters

Added to the same global by deck-extras.js and deck-adapters.js. If you are not loading those files, these are undefined.

const ok = await Deck.copy(input.value);
Deck.toast(ok ? 'Copied' : { kind: 'bad', title: 'Could not copy' });

node.innerHTML = Deck.qr.svg('https://example.com/ticket/1042', 'H');

Deck.adapters.available.chart;   // false
Deck.adapters.report();
// { placement: 'CSS anchor positioning',
//   editor: 'Deck built-in (execCommand)',
//   charts: 'Deck CSS charts', … }

if (Deck.adapters.available.chart) {
  Deck.chart(canvas, { type: 'line', data });
}

Properties

What still works with the scripts removed

Worth knowing before you reach for any of the above. The modal, drawer, sheet, popover and tooltip are the platform's own <dialog> and popover APIs; the accordion is <details>; tabs, the carousel's dots and arrows, the segmented control and the whole of forms are CSS. Sorting a data grid, picking a date on the custom calendar, encoding a QR code and firing a toast are the things that genuinely need script.

So the honest test for a page is whether the scripts are doing work the platform cannot. If deleting deck-extras.js changes nothing on a page, do not ship it.