Every knob, event and edge case.

01 Install

Two files and one script tag. Which of the two builds to use, and what each does the moment it loads.

Refrakt ships two builds and one stylesheet. Both builds are the same engine — the only difference is that the UMD build auto-initializes and the ESM build never does.

Script tag (no build step)

Drop the two files on your page. The UMD build calls Refrakt.auto() once on DOMContentLoaded (immediately if the document has already loaded), which initializes every element carrying a data-refrakt attribute. You write no JavaScript.

<link rel="stylesheet" href="lib/refrakt.css">

<div id="hero" data-refrakt="atelier">
  <figure class="rf-slide">
    <img src="img/look-1-lqip.jpg" data-rf-src="img/look-1.jpg"
         alt="Model in a pleated ivory coat">
    <figcaption class="rf-text"><h2>Atelier</h2></figcaption>
  </figure>
  <!-- more .rf-slide figures -->
</div>

<script src="lib/refrakt.umd.js"></script>

The UMD build also exposes the class as window.Refrakt, so you can construct instances by hand alongside auto-init. Constructing on an element that auto-init already bound warns once and hands you back the existing instance rather than making a second one.

Bundler (ESM)

The package's exports map resolves refrakt to the ESM build and refrakt/css to the stylesheet. The ESM build never auto-runs — it checks document.currentScript, which is null for module execution — so you construct instances yourself, or call Refrakt.auto() when your app has mounted its DOM.

import Refrakt from 'refrakt';
import 'refrakt/css';

const slider = new Refrakt('#hero', {
  preset: 'prism-noir',
  glass: { ior: 0.12 },
  lightbox: { enabled: true },
});

slider.on('ready', ({ slideCount, mode }) => {
  console.log(`${slideCount} slides, running in ${mode} mode`); // 'gl' | 'css'
});

slider.on('change', ({ index, previousIndex, source }) => {
  console.log(index, previousIndex, source); // source: 'drag' | 'api' | 'autoplay' | …
});

TypeScript definitions ship at types/refrakt.d.ts and are wired into the same export. Refrakt.version returns the build's semver string.

02 The markup contract

The exact HTML a slide must contain. Four requirements; everything else on the page is yours.

Refrakt enhances real DOM. What you author is what search engines index, what screen readers read, and what a visitor sees before the script runs. The engine's requirements are narrow and exact.

<div id="hero" data-refrakt="frost">

  <figure class="rf-slide">
    <img src="img/plate-1-lqip.jpg" data-rf-src="img/plate-1.jpg"
         alt="Cut crystal tumbler on green felt">
    <figcaption class="rf-text">
      <h2>Plate One</h2>
      <p>Hand-cut lead crystal, 1962.</p>
    </figcaption>
  </figure>

  <figure class="rf-slide">
    <img src="img/plate-2-lqip.jpg" data-rf-src="img/plate-2.jpg"
         alt="Decanter, backlit">
    <figcaption class="rf-text"><h2>Plate Two</h2></figcaption>
  </figure>

</div>

What the engine actually requires

• The container is any block element. It needs a real size from your CSS — height: 100vh, a fixed height, or aspect-ratio. Slides are absolutely positioned at init, so a container with no explicit height collapses to zero and you see nothing.
• Slides are found with :scope > .rf-slide — direct children only. A wrapper <div> between the container and the slides breaks detection completely. At least one is required.
• The class is load-bearing, the tag is not. <figure class="rf-slide"> is the convention (and what <figcaption> pairs with), but the engine matches on .rf-slide.
• Slide order is source order. Indices are 0-based.
• Media is the first <img> inside the slide. Its inline src is the placeholder; data-rf-src is the full-resolution file. Video and provider slides use per-slide attributes on the <figure> instead — see Media.
• .rf-text is one optional element per slide. At init it is moved into a synced .rf-text-layer that tracks the rendered scene every frame; the engine only writes transform, opacity and visibility on it. The content stays real, selectable, crawlable DOM, and destroy() returns each node to its original parent and sibling position.
• Original media is hidden, not removed. Your <img>/<video> elements get visibility: hidden (so they keep decoding and stay in the accessibility tree) while the WebGL canvas paints the pixels. Anything inside .rf-text is left alone.

Zero slides, or a selector that matches nothing

Neither throws. The constructor emits exactly one console.warn and returns an inert stub instance: every method is a no-op that returns this, getIndex() and getProgress() return -1, and no DOM is touched.

new Refrakt('#does-not-exist');
// [Refrakt] element not found for "#does-not-exist"; instance is inert

new Refrakt(emptyDiv);
// [Refrakt] container has no .rf-slide children; instance is inert

Changing slides later

Add or remove .rf-slide children in the DOM, then call rebuild(). It is a destroy() plus re-init on the same element: the current index is captured first and reused as the start index, and every handler registered with .on() is preserved across the rebuild, so ready fires again into your existing subscribers.

03 Data attributes

Setting options in HTML rather than JavaScript — and the order in which the four sources of configuration override one another.

Container attributes

Read once, at new Refrakt() / Refrakt.auto().

<div id="hero"
     data-refrakt="atelier"
     data-rf-options='{"motion": {"autoplay": {"enabled": true, "interval": 5500}},
                       "nav": {"counter": true, "spectrum": false},
                       "hash": true}'>
  <!-- .rf-slide children -->
</div>

Note the quoting: the attribute is wrapped in single quotes so the JSON can use its required double quotes. Single-quoted JSON keys are the most common cause of the parse warning.

The merge chain

Four sources are deep-merged in this order — later wins, leaf by leaf:

1. Defaults — the full option tree. This is the client-safe preset.
2. Preset — whatever the named preset declares. Anything it does not declare falls through.
3. data-rf-options — the page-level override.
4. Constructor options — the object passed to new Refrakt(el, options).

Plain objects merge key by key; arrays and scalars replace wholesale. The merged result is then validated leaf by leaf against the schema:

• Out-of-range numbers are clamped to the nearest bound, with one warn (glass.ior 0.9 clamped to 0.35).
• Wrong-typed values fall back to the default, with one warn.
• Unknown paths are dropped, with one warn (unknown option "glass.iro" ignored).

Every warning fires at most once per instance per cause. A bad config produces a different look, never a broken slider — the engine never throws on configuration.

Which preset name wins

The preset key is resolved before the merge, from the first source that supplies one: options.preset → data-rf-options.preset → data-rf-preset → data-refrakt → 'client-safe'. An unregistered name warns (unknown preset "…"; using defaults) and the instance runs on defaults rather than failing.

Per-slide attributes

On each .rf-slide. Media sources are mutually exclusive and resolve in this priority: data-rf-youtube / data-rf-vimeo → data-rf-video → data-rf-srcset → data-rf-src → the inline <img src>.

04 Options reference

Every setting the engine accepts, with its type, default and exact range. Generated from the engine’s own validation schema. Filter it; do not read it end to end.

Every row below is generated from the engine's own validation schema — the same table setOption() clamps against at runtime, so the types, ranges and defaults here cannot drift from the code. Options marked live apply on the next frame; those marked rebuild() are stored and take effect on the next rebuild() call. Values outside a range are clamped (with one console warning), never rejected.

No option matches that filter.

05 Presets

The eight named looks, exactly what each one sets, and how to register your own.

Eight bundles ship with the engine. A preset is nothing but a partial options object merged under yours — defaults ← preset ← data-rf-options ← constructor — so anything a preset does not declare falls through to the defaults, and anything you declare beats it. Presets carry no colours: the ink/paper pairing named below is yours to set (see Theming).

Each one is running live on its own page.

06 API

Driving the slider from your own JavaScript: constructing instances, moving between slides, changing settings live, tearing down cleanly.

Every mutating method returns the instance, so calls chain. The readers return values, and destroy() returns nothing. After destroy() every method is a warn-once no-op — nothing throws.

Statics

Instance methods

07 Events

What the slider tells you, and when. One table — every payload listed is the real shape you receive.

Subscribe with .on(name, fn) and drop with .off(name, fn). Every payload carries at least instance (the public Refrakt) and index (the committed index at emit time); the fields below are what each event adds on top. Subscriptions live on the wrapper, so they survive rebuild() and the runtime GL → CSS fallback swap.

08 Media

Preparing images and video: sizes, formats, the loading pipeline, and the GPU memory behind it all.

Everything the engine draws — images, video frames, provider posters — becomes a WebGL texture sampled through the optics shader. Slides are cover-fit: scaled to fill the container, cropped on the overflowing axis, exactly like CSS object-fit: cover.

Images

• 1600 px on the longest edge is the sweet spot for full-bleed heroes.
• Textures are capped at 2048 px internally, whatever the source file or the device pixel ratio. Pixels beyond that cost bytes and decode time and are never displayed. Do not ship 4000 px files.
• Keep one aspect ratio per slider. Cover-fit hides mismatches by cropping, but consistent framing keeps focal points and captions predictable.
• JPEG at quality 75–82. The optics pass lays grain and light over the image, which masks compression far better than a static viewer would.

Responsive sources

data-rf-srcset takes the same syntax as native srcset, but only width descriptors (800w). Density descriptors (2x) do not parse and are ignored.

<img src="img/peak-lqip.jpg"
     data-rf-srcset="img/peak-800.jpg 800w,
                     img/peak-1600.jpg 1600w,
                     img/peak-2048.jpg 2048w"
     alt="North face at dawn">

Selection runs once, when the slide enters the preload window. The target width is the container's CSS width × min(devicePixelRatio, quality.maxDPR) (DPR capped at 2 by default). The smallest candidate ≥ target wins; if none is large enough, the largest available is used. Resizing the window afterwards does not re-fetch a bigger candidate — selection is deliberately one-shot so a window drag-resize cannot trigger a download storm.

Lazy loading

On by default. Only the current slide ± media.preload neighbours (default 1, range 0–3) are fetched, and the window self-advances mid-drag — it re-centres on every half-slide crossing, so the incoming slide is already decoding before you release. An offscreen slider defers its first decode entirely until it scrolls into view. Set media.lazy: false to eager-load every slide.

The frost-up reveal

Loading is part of the look, not something to hide. The inline <img src> is the low-quality placeholder by contract:

1. The LQIP uploads immediately and renders behind procedural frost — the frost surface is forced on while loading, whatever glass kind the slider is configured with. A frosted LQIP on screen counts as ready; the slider never blocks on full-resolution files.
2. The full file decodes off the critical path. The texture swap is gated to an idle frame, so it never lands mid-gesture and never pops.
3. On swap the frost veil melts over 600 ms on cubic-bezier(0.33, 0, 0.2, 1), revealing the sharp image — condensation clearing from glass. Under reduced motion it becomes a 200 ms linear fade.

Keep the LQIP at 64 px or less on the long edge, same aspect ratio, quality ~50 — 1–2 KB, and the first paint is effectively free. media.frostUp: false disables the choreography: the LQIP renders as-is and the full image swaps in hard.

If a slide has only an inline src and no data-rf-src, that file is treated as both placeholder and final image. Fine for a thumbnail strip; wrong for a hero.

Self-hosted video

Self-hosted video renders inside the optics: frames are uploaded to a texture every frame and refract, disperse and relight like any image.

<figure class="rf-slide"
        data-rf-video="video/reel-01.mp4"
        data-rf-poster="img/reel-01-poster.jpg">
  <img src="img/reel-01-lqip.jpg" alt="Reel 01 — title sequence">
  <figcaption class="rf-text"><h2>Title Sequence</h2></figcaption>
</figure>

• MP4 / H.264. The one codec every supported browser decodes. HLS (.m3u8) plays only where natively supported (Safari/iOS) — no hls.js is bundled, and the zero-dependency rule means there never will be. Elsewhere the slide falls back to its poster.
• Muted autoplay only. muted and playsinline are forced whenever autoplay is in effect, because unmuted autoplay is blocked by every modern browser. If a browser still refuses the first play(), the poster stays up and playback retries on the visitor's next interaction.
• A video plays only while its slide is the committed centre slide and the tab is visible. Leaving centre pauses it — resume, not restart. Off-window videos cost nothing per frame.
• A shared pool of at most 4 <video> decoders serves every instance on the page (mobile Safari caps concurrent decoders). With more simultaneous video slides than that, the furthest-from-centre slides show their poster stills — which is why data-rf-poster is not optional.
• Defaults live under media.video: { muted: true, autoplay: true, loop: true, playsinline: true }.

Each time a self-hosted video actually starts playing (first autoplay and every resume) the instance emits mediaplay with { media: HTMLVideoElement }.

YouTube and Vimeo — the poster pattern

The honest limitation first: a cross-origin iframe can never be a WebGL texture. No library can refract live YouTube or Vimeo playback, and Refrakt does not pretend to. Provider slides instead use the poster pattern — a still image renders inside the optics (it refracts, tears and frosts like any slide, and gets a .rf-play-badge), and clicking it opens playback in a lightbox iframe.

<figure class="rf-slide"
        data-rf-youtube="dQw4w9WgXcQ"
        data-rf-poster="img/talk-poster.jpg">
  <img src="img/talk-lqip.jpg" alt="Keynote — opening talk">
  <figcaption class="rf-text"><h2>Keynote</h2></figcaption>
</figure>

Provider slides force their own lightbox on even when lightbox.enabled is false — playback has nowhere else to go. Lightbox playback uses the privacy-enhanced endpoints: youtube-nocookie.com/embed and player.vimeo.com.

If you omit data-rf-poster, the engine derives one: for YouTube it probes maxresdefault and detects the grey 120×90 stub, falling back to hqdefault; for Vimeo it makes an oEmbed API call, which fails offline, on private videos, and at Vimeo's discretion (Vimeo oEmbed failed for <id>; supply data-rf-poster).

CORS

WebGL may only sample images the page is allowed to read, so every image and video is requested with crossorigin="anonymous". Same-origin files need nothing. Cross-origin files (CDN, object storage) must send Access-Control-Allow-Origin — without it the browser blocks the texture upload, the LQIP stays up, and you get one console warning. If your CDN cannot send the header, serve slider media from the page's own origin; everything else works identically.

The lightbox

lightbox.enabled (default false) gates only the built-in click trigger. openLightbox() always works regardless:

slider.openLightbox();        // current slide
slider.openLightbox(3);       // a specific index
slider.closeLightbox();

slider.on('lightboxopen',  () => document.body.dataset.modal = 'open');
slider.on('lightboxclose', () => delete document.body.dataset.modal);

With lightbox.deRefract (default true) the open animation irons the glass distortion flat before the image expands; it is skipped under reduced motion and in CSS fallback mode. The lightbox is a role="dialog" / aria-modal element appended to document.body — style it from a global stylesheet, not a scoped one. Focus moves into it on open and returns to the invoking element on close, Tab is trapped inside it, and Esc closes it. Opening a self-hosted video slide migrates the real <video> element into the lightbox with native controls — and because a user gesture opened it, sound is allowed there.

Texture memory — auto-managed

You do not manage GPU memory. The engine does, against a flat 96 MiB budget shared by every instance on the page:

• Full-resolution textures are held for the current slide ± media.preload neighbours. Slides beyond that window become eviction candidates.
• While the budget is exceeded, the least-recently-rendered candidate is evicted — on idle frames only, never mid-gesture. An evicted slide quietly reverts to its LQIP texture; if it re-enters the window the full file re-fetches (from HTTP cache) and frosts back up. The current slide and its immediate neighbours are never evicted.
• Each texture costs roughly width × height × 4 × 1.34 bytes — the 1.34 covers the mip chain. A 1600×1000 image is about 8.6 MB of GPU memory.
• The budget and the LRU list are global to the shared context, so ten product vitrines on one page cannot stampede the GPU any harder than a single hero.

Follow the 1600 px guidance and roughly ten slides stay fully resident at once. Beyond that the engine rotates textures and, on a working network, you will not notice.

09 Theming

Two custom properties retheme every control on the slider. Everything beyond that is a stable class name you can style normally.

All shipped chrome — text, arrows, dots, counter, editorial menu, progress rule, focus rings, scrims, the lightbox backdrop — derives from exactly two custom properties. Set them and you have rethemed everything. There is no third token to learn.

<style>
  /* the container gets .rf-root at init; set the tokens there or on any ancestor */
  #hero {
    --rf-ink:   #111111;  /* text, icons, active states, fills */
    --rf-paper: #fafafa;  /* scrims, control backdrops, lightbox backdrop */
    height: 100vh;
  }
</style>

Those two values are also the built-in defaults, declared on .rf-root in refrakt.css. Everything else is derived: control backdrops and the .rf-scrim utility are paper at 72% (via color-mix, falling back to solid paper where unsupported), muted chrome is ink at reduced opacity, and the focus ring is a 2 px ink outline with a 2 px offset.

The two documented pairings

<style>
  /* light chrome — client-safe, boardroom, atelier, frost */
  #hero-light { --rf-ink: #111111; --rf-paper: #fafafa; }

  /* dark chrome — prism-noir, darkroom, eclipse, spectra */
  #hero-dark  { --rf-ink: #f5f2ea; --rf-paper: #0c0c0e; }
</style>

Styleable parts

Every piece of chrome is plain DOM built from real <button> elements with a stable class name. Override freely — but see Accessibility on contrast and hit targets before you shrink anything.

10 Accessibility

What the engine handles on your behalf, and the handful of things that remain your responsibility.

What the engine does for you

ARIA carousel pattern

Applied at init, restored attribute-for-attribute by destroy(), following the WAI-ARIA APG carousel pattern.

• Container: role="region", aria-roledescription="carousel", aria-label from a11y.label (default 'Image carousel'), and tabindex="0" if it did not already have one. If you supplied your own aria-label or aria-labelledby, it is preserved, never overwritten — including by later setOption('a11y.label', …) calls.
• Each slide: role="group", aria-roledescription="slide", aria-label="3 of 8". Every non-current slide gets aria-hidden="true" and its focusable descendants get tabindex="-1" (originals recorded and restored when the slide becomes current). A virtual cursor therefore sees exactly one slide's content plus the controls, not a wall of eight captions.
• Focus safety: if the committed slide changes while focus sits inside a slide that just became hidden, focus moves to the container root — never to a hidden element.
• What screen readers actually read is your original DOM — real alt text and real caption content. The canvas is aria-hidden presentation.

Live region

A visually-hidden aria-live="polite", aria-atomic announcer reports "Slide 3 of 8: Title" on change — the title being the slide's first heading (h1–h6), empty if there is none. Writes are debounced 150 ms, so a rapid multi-slide drag announces only the landing slide. Announcements are suppressed while a change came from autoplay (a polite region firing every six seconds is noise) and resume the moment the user navigates. a11y.announceSlides: false disables the live region only — the structural ARIA always ships.

Keyboard

Keys are ignored while a drag is in flight, when the event was already preventDefaulted, and whenever focus is in an <input>, <textarea>, <select> or a contenteditable region — so a search box inside a slide still works. motion.keyboard: false turns the map off. Navigating via the dots or the editorial menu does not steal focus; the live region announces instead.

Reduced motion

The engine reads prefers-reduced-motion at init and subscribes to changes — flipping the OS setting takes effect on the next transition, with no reload. Reduced-motion users stay on the WebGL path; they do not get the fallback. What changes: transitions become an opacity dissolve, velocity-driven effects (shear, dispersion tear, RGB echo, text parallax) pin to zero, and the frost-up reveal shortens to a 200 ms linear fade. The effective state is mirrored onto the container as data-rf-reduced, which the stylesheet uses to kill transitions and animations. a11y.reducedMotion overrides it: 'auto' follows the OS, 'always' forces reduced, 'never' forces full motion.

Autoplay pause control (WCAG 2.2.2)

Whenever autoplay is enabled a visible pause button is mounted, and nav options cannot remove it. This is hard-coded on purpose. It is a real <button> with aria-pressed and a label that swaps between "Pause slideshow" and "Play slideshow". Pausing is sticky: no timer, hover-out or slide change restarts it — only the user, or an explicit play() call. motion.autoplay.pauseOnHover additionally suspends the timer on hover and on focus. All interactive chrome meets a 44×44 px minimum hit target.

Fixed UI strings

a11y.label is the only configurable UI string in v1. Everything else — "Previous slide", "Next slide", "Go to slide {i} of {n}", "Pause slideshow" / "Play slideshow", "Close fullscreen view", "Media viewer", the "{i} of {n}" slide labels and the "Slide {i} of {n}: {title}" announcement — is a fixed English constant.

What you still have to do

• Alt text on every image. The engine reads img.alt and carries it through to the lightbox, but it does not validate it and will not warn you. A missing alt is a silent failure. Mark genuinely decorative images alt="" explicitly.
• Contrast. If you set your own ink/paper pair, keep it at 4.5:1 or better for text and 3:1 for non-text chrome. Both documented pairs sit far above that.
• Text over imagery is your risk. A caption's legibility depends on the photograph underneath it, which the engine cannot know. Back it with the shipped .rf-scrim utility.
• A meaningful label. Set a11y.label (or your own aria-label) to something better than the default — "Spring 2026 lookbook", not "Image carousel".
• Captions for video. Any <track> you author passes through untouched. The engine never synthesizes one.

11 Performance & fallback

How the engine protects its frame rate on weak hardware, and what a visitor without WebGL2 gets instead.

The auto quality governor

One governor runs per shared GL context, aggregating the quality config of every instance on the page (strictest fpsFloor wins, largest maxDPR wins).

It measures the p95 of the last 60 animating frames — deltas between consecutive animating rAF timestamps only, so idle and breathing frames never pollute the sample. If p95 exceeds 1000 / fpsFloor for three consecutive windows, the governor drops one step down a five-step ladder:

1. Steps 1–3 tighten the device-pixel-ratio cap progressively (1.5, then 1.25, then 1.0), below whatever quality.maxDPR already allows. Fewer pixels, identical shader.
2. Step 4 additionally switches every instance whose quality.tier is 'auto' to the lite shader tier — the cheaper optics path.

Recovery is deliberately slow and asymmetric: after 30 seconds of clean windows the governor climbs back exactly one step, and the upgrade timer resets on any borderline window (there is a hysteresis band at 80% of the threshold) and on every visibilitychange. It never yo-yos, and it never promotes in the middle of a bad patch.

Pinning the tier opts out of the shader half of the ladder: with quality.tier: 'high' or 'lite' the governor still manages DPR (steps 1–3) but never touches your shader choice. An all-lite page also caps DPR at 1.5 from the start.

Render on demand

There is exactly one requestAnimationFrame loop for the whole page, owned by the renderer, and every instance is scissored into the same shared canvas — one WebGL draw call per instance per frame, and no instance ever schedules its own frame.

The loop parks itself the moment nothing needs drawing: no instance is dragging, seeking, running a timeline or playing video, and no visible instance is breathing or drifting. A settled slider that nobody is touching costs zero frames — not a cheap frame, no frame. Any dirty source (an option write, a resize, a texture swap, a pointer event) wakes it again. document.hidden parks everything unconditionally and pauses video decoding with it. Sliders scrolled out of the viewport keep their integrators ticking but stop being drawn, and their last pixels are erased from the shared canvas so nothing bleeds through.

Memory

A flat 96 MiB texture budget, shared by every instance on the page. Full-resolution textures outside the current slide ± media.preload window are eviction candidates; while the budget is exceeded the least-recently-rendered candidate is dropped back to its LQIP, on idle frames only. The current slide and its immediate neighbours are never evicted. Textures are capped at 2048 px regardless of DPR. See Media for the full accounting.

The CSS fallback mode

When WebGL2 is unavailable, Refrakt mounts a complete non-GL implementation of the same instance: same markup, same options, same methods, same events, same gesture physics (pointer, wheel and keyboard feed the identical integrator). Transitions become crossfades, and lens-mode side slides get a backdrop-filter glass twin instead of refraction. Buyer code never branches.

It engages for exactly three reasons, each announced by a fallback event carrying { reason }:

const slider = new Refrakt('#hero');

slider.on('fallback', ({ reason }) => {
  // 'no-webgl2' | 'forced' | 'context-lost'
  console.log('Refrakt is in CSS mode:', reason);
});

// 'fallback' fires BEFORE 'ready' in the no-webgl2 and forced cases.
slider.on('ready', ({ mode }) => {
  document.body.dataset.rfMode = mode; // 'gl' | 'css'
});

In CSS mode the container carries both .rf-css-mode and .rf-fallback; style the latter. GL-only options (glass.*, dispersion.*, light.*) are still accepted, validated and stored — reading them back returns what you set — they simply have nothing to drive. And because CSS mode renders entirely inside the container rather than on a page-level fixed canvas, forceFallback: true is also the escape hatch for pages whose layout puts a transform or filter on an ancestor of the slider (see Troubleshooting).

12 Recipes

Copy-pasteable answers to the things buyers actually ask for. Real methods, real option paths, real event payloads — nothing here is pseudo-code.

Copy-pasteable answers to the things buyers actually ask for. Every snippet below uses only real methods, real option paths and real event payloads — nothing is pseudo-code. All recipes assume you have an instance:

// UMD (window.Refrakt) or: import Refrakt from 'refrakt';
const slider = new Refrakt('#hero');            // selector or HTMLElement

Mutating methods chain (next, prev, goTo, setOption, play, pause, openLightbox, closeLightbox, on, off, rebuild); the readers (getIndex, getProgress, getOption) return values, and destroy() returns nothing.

Register a custom preset

Refrakt.registerPreset() is a static and must run before the instance that uses it is constructed. It accepts a full preset file ({ meta, options }) or a bare options object.

Refrakt.registerPreset('house-style', {
  meta: { name: 'house-style', version: '1.0.0', description: 'Brand slider' },
  options: {
    glass: { kind: 'reeded', ior: 0.12,
             reeded: { frequency: 18, depth: 0.6, sheen: 0.5 } },
    dispersion: { amount: 0.2, velocityGain: 0.45, maxTear: 0.3 },
    nav: { spectrum: false, counter: true }
  }
});

// Bare options work too:
Refrakt.registerPreset('flat', { glass: { kind: 'none' } });

// Use it — explicitly…
const slider = new Refrakt('#hero', { preset: 'house-style' });
// …or from markup: <div data-refrakt="house-style">

Refrakt.presets['house-style'].meta.description; // frozen registry, read-only

Options are validated at registration: out-of-range numbers are clamped, unknown keys are dropped, and re-registering a name overwrites it with a console warning. The merge order is factory defaults ← preset ← data-rf-options ← constructor options.

Wire external prev / next buttons

// Turn the built-in arrows off if you're supplying your own chrome.
const slider = new Refrakt('#hero', { nav: { arrows: false } });

document.querySelector('#prev').addEventListener('click', () => slider.prev());
document.querySelector('#next').addEventListener('click', () => slider.next());

// Jump straight to a slide; { instant: true } skips the animation.
document.querySelector('#last').addEventListener('click', () => slider.goTo(4));

next() and prev() wrap when layout.loop is true (the default) and are animated. Both chain, so slider.prev().prev() steps back two.

Sync custom pagination to the change event

ready hands you slideCount; change fires exactly once per committed index change, whatever caused it.

const slider = new Refrakt('#hero', { nav: { spectrum: false } });
const bar = document.querySelector('#dots');
let dots = [];

slider.on('ready', (e) => {
  // e.slideCount, e.mode ('gl' | 'css'), e.instance, e.index
  bar.textContent = '';
  dots = Array.from({ length: e.slideCount }, (_, i) => {
    const b = document.createElement('button');
    b.type = 'button';
    b.setAttribute('aria-label', 'Go to slide ' + (i + 1));
    b.addEventListener('click', () => slider.goTo(i));
    bar.appendChild(b);
    return b;
  });
  paint(e.index);
});

slider.on('change', (e) => {
  // e.index, e.previousIndex, e.source, e.instance
  // source: 'drag' | 'api' | 'autoplay' | 'keyboard' | 'wheel' | 'hash'
  paint(e.index);
});

function paint(i) {
  dots.forEach((b, n) =>
    b.setAttribute('aria-current', n === i ? 'true' : 'false'));
}

Every payload also carries instance and index. Subscribing to ready after it has already fired replays it immediately, so load order never costs you the event.

Autoplay with a pause control

const slider = new Refrakt('#hero', {
  motion: { autoplay: { enabled: true, interval: 6000, pauseOnHover: true } }
});

const btn = document.querySelector('#autoplay-toggle');
btn.addEventListener('click', () => {
  const on = slider.getOption('motion.autoplay.enabled');
  if (on) slider.pause(); else slider.play();
  btn.setAttribute('aria-pressed', String(!on));
  btn.textContent = on ? 'Play' : 'Pause';
});

play() and pause() write motion.autoplay.enabled, so getOption() always reflects the true state of your button. interval is clamped to 1500–60000 ms.

Deep-link slides with the hash option

<!-- The container MUST have an id — the hash is built from it. -->
<div id="gallery" data-refrakt="atelier" data-rf-options='{ "hash": true }'>
  <figure class="rf-slide">…</figure>
</div>

const slider = new Refrakt('#gallery', { hash: true });

slider.on('change', (e) => {
  if (e.source === 'hash') console.log('arrived via back/forward');
});

• The hash is #<container-id>-<n> and 1-based: #gallery-3 is the third slide.
• No id on the container means no hash — the option silently does nothing.
• On load the hash wins over layout.startIndex.
• Each settled transition pushes a history entry, so Back returns to the previous slide; commits mid-flight only replace it.
• While the lightbox is open the hash gains a /view suffix (#gallery-3/view), and Back closes the lightbox.

Opt a slide into the lightbox

lightbox.enabled turns the click-to-open trigger on for the whole instance. What a slide shows in the lightbox comes from its media attributes.

<div data-refrakt="atelier" data-rf-options='{ "lightbox": { "enabled": true } }'>

  <!-- data-rf-src is the full-size source the lightbox opens -->
  <figure class="rf-slide">
    <img src="img/01-lqip.jpg" data-rf-src="img/01-full.jpg" alt="Look 01">
  </figure>

  <!-- self-hosted video: opens with native controls, unmuted -->
  <figure class="rf-slide" data-rf-video="video/reel.mp4"
          data-rf-poster="img/reel-poster.jpg">
    <img src="img/reel-lqip.jpg" alt="Showreel">
  </figure>

  <!-- data-rf-youtube / data-rf-vimeo force THIS slide's lightbox on,
       even when lightbox.enabled is false -->
  <figure class="rf-slide" data-rf-youtube="dQw4w9WgXcQ"
          data-rf-poster="img/talk-poster.jpg">
    <img src="img/talk-lqip.jpg" alt="Keynote">
  </figure>
</div>

slider.openLightbox();     // current slide
slider.openLightbox(2);    // by index (wrapped when looping, else clamped)
slider.closeLightbox();    // idempotent

slider.on('lightboxopen',  () => document.body.classList.add('is-viewing'));
slider.on('lightboxclose', () => document.body.classList.remove('is-viewing'));

A slide with an <img> always has something to show — data-rf-src if present, otherwise the image's own src. A slide with neither an image nor video/poster/YouTube/Vimeo attributes refuses to open and warns to the console. Links and buttons inside .rf-text never trigger the lightbox, so captions stay clickable.

Switch optics live with setOption()

// One dot-path…
slider.setOption('glass.kind', 'wedge');

// …or a batch, deep-merged in a single call:
slider.setOption({
  glass: { kind: 'wedge', ior: 0.2,
           wedge: { angle: 22, width: 0.24, gain: 1.6 } },
  dispersion: { amount: 0.85, velocityGain: 1.4, maxTear: 1.0 },
  exposure: { bloom: 0.3, grain: 0.12 },
  text: { rgbEcho: true }
});

slider.getOption('glass.ior');   // 0.2 — the resolved, post-clamp value

Everything under glass, dispersion, light, exposure, motion, text, nav, lightbox, a11y, quality and hash applies on the next frame. Out-of-range numbers are clamped (glass.ior 0–0.35, dispersion.maxTear 0–1) with a one-time console warning — a bad value gives you a different look, never a broken slider.

A handful of keys are stored but need a rebuild: preset, layout.mode, layout.startIndex, every media.* key, forceFallback and debug.

slider.setOption('layout.mode', 'lens').rebuild(); // keeps index + handlers

Frosted condensation wipe (pointer clears the glass)

The clear-patch interaction needs three things together — a hero frost pane that is permanently on (glass.frost.mode: 'rest'), a pointer-driven light, and a non-zero clearRadius. On the default 'transition' mode the pane is a veil that is fully clear at rest, so clearRadius has nothing to wipe.

const slider = new Refrakt('#testimonials', {
  glass: { kind: 'frost', frost: { mode: 'rest', coverage: 0.95, scale: 220 } },
  light: { followPointer: 0.5, clearRadius: 0.65 }
});

Force the CSS fallback (for testing)

The GL-vs-CSS decision is made once, at construction. Pass forceFallback to the constructor, or put it in data-rf-options.

const slider = new Refrakt('#hero', { forceFallback: true });

slider.on('fallback', (e) => console.log(e.reason)); // 'forced'
slider.on('ready',    (e) => console.log(e.mode));   // 'css'

<div data-refrakt="atelier" data-rf-options='{ "forceFallback": true }'>

slider.destroy();                                  // restores the original DOM
const cssSlider = new Refrakt('#hero', { forceFallback: true });

The same fallback event fires on its own with reason: 'no-webgl2' when the browser has no WebGL2, and reason: 'context-lost' after an unrecovered GPU context loss. In every case the public API is identical — the same methods, the same events, the same option paths.

13 Troubleshooting

Every console warning the engine can emit, what causes it, and what to do about it.

Refrakt is engineered to degrade rather than break: bad options clamp, missing media falls back, a machine without WebGL2 gets a CSS slider with the identical API. When something still looks wrong it is almost always one of the rows below — and almost always already announced by a [Refrakt] line in the browser console. Open the console first. Every warning fires at most once per cause and never accompanies an exception.

Strict CSP

Refrakt is CSP-friendly by construction: no eval, no Web Workers, no runtime style injection, no inline scripts, no external fetches for its own code. What your policy must allow depends only on where your media lives — img-src for slide images, media-src for self-hosted MP4s, frame-src for www.youtube-nocookie.com / player.vimeo.com if you use provider slides, and connect-src vimeo.com only if you rely on Vimeo poster derivation instead of supplying data-rf-poster. A fully self-hosted page — own images, own MP4s, data-rf-poster on provider slides — runs under default-src 'self' with no exceptions at all.