Your pictures, behind glass.

01 What you downloaded

Unzip the download and you get three folders and two short text files. That is all there is:

Keep the three folders together, side by side, exactly as they came out of the zip. The demo pages find the slider by looking one folder up, so moving them apart breaks those links.

02 Build it once

This download ships the complete source code of the slider rather than a pre-packed file. Turning that source into the two files your web page actually loads takes one command, and you only ever do it once.

You will need Node.js version 20 or newer — a free install from nodejs.org, about two minutes. It is needed for this build only. Nothing about your finished website depends on it, and your visitors never touch it.

Open a terminal (macOS: Terminal; Windows: PowerShell or Command Prompt), move into the refrakt folder from the download, and run three lines:

cd refrakt      # the folder that contains package.json
npm install     # downloads the build tools — about 30 seconds
npm run build   # builds the slider — about 5 seconds

When it finishes you will have a new folder, refrakt/dist/, containing:

Never run a terminal command before? The build is safe to repeat — run it as often as you like, it always produces exactly the same result. If the third line reports an error, the common causes and their fixes are on the Troubleshooting page.

03 See it working

Open demos/index.html in your browser — just double-click the file. No web server, no setup. You will get a hub page linking to all ten demos.

Click through them and find the one closest to what you are building. That page is your starting point for everything below.

04 Use your own pictures

This is the part everyone comes for, and it is genuinely one line of HTML per picture.

The one thing to understand

Every slide is a plain <figure> holding an ordinary <img> tag. That is it. The glass, the light and the refraction are applied on top of that image while the page runs — nothing is baked into the file. Your photograph stays a normal web image that you can open, edit and replace like any other.

<figure class="rf-slide">
  <img src="img/harbour.jpg" alt="Fishing boats at dawn">
</figure>

Change img/harbour.jpg to the path of your picture. Change the alt text to describe it. Save. Reload. That is your photograph, behind the glass.

Step by step

1. Copy the demo folder you liked. If it was atelier, duplicate demos/atelier/ and rename the copy to whatever you want. Work in the copy, so the original stays intact for reference.

2. Put your images somewhere. Easiest: make an img folder inside your copy and drop them in. JPG, PNG and WebP all work.

3. Open index.html in a text editor and search for rf-slide. You will find one block per slide, one after another.

4. Point each <img> at your file and rewrite its alt.

5. Save and reload the page. Your pictures are in the glass.

What the demo markup looks like, and what to change

The demos use a slightly longer form than the one-liner above, because they are tuned for loading speed. Here is a real slide from demos/atelier/index.html with the parts you edit marked:

<figure class="rf-slide">
  <img src="../assets/img/atelier-1-lqip.jpg"          <!-- (1) tiny preview -->
       data-rf-src="../assets/img/atelier-1.jpg"        <!-- (2) the real photo -->
       alt="Soft-focus study of deep sienna fabric">    <!-- (3) describe it -->
  <figcaption class="rf-text">
    ...
  </figcaption>
</figure>

Don't want to make two versions of every photo?

Then don't. Delete the data-rf-src line and put your real photo in src. The slider uses whatever it is given:

<figure class="rf-slide">
  <img src="img/harbour.jpg" alt="Fishing boats at dawn">
</figure>

Everything else works identically. You give up one thing: the "frost-up" effect, where a slide starts clouded and clears as the full photo arrives. With a single image there is nothing to clear from, so the slide simply fades in instead. That is the whole trade-off. You can add the small previews later if you decide you want them — it is the same one line, put back.

Picture sizes

05 Use your own words

Captions are plain HTML too. Each slide can carry a <figcaption class="rf-text">, and whatever you put inside it appears over the slide:

<figure class="rf-slide">
  <img src="img/harbour.jpg" alt="Fishing boats at dawn">

  <figcaption class="rf-text">
    <h2>Harbour, 5 a.m.</h2>
    <p>The fleet goes out before the light does.</p>
  </figcaption>
</figure>

Type your headline between the <h2> tags and your sentence between the <p> tags. Save, reload.

Things worth knowing

• It is real text, not painted into the picture. Visitors can select and copy it, screen readers read it, search engines index it, and it stays sharp on every screen.
• No caption? Leave the whole <figcaption> block out. The slide shows just the image.
• Use whatever tags you want inside it — headings, paragraphs, a link, a button. It is ordinary HTML in an ordinary place.
• Some demos use different tags. atelier, for instance, uses <span>s with classes like look-name so that page can style them its own way. Don't let it throw you: the text between the tags is still just text. Replace the words and leave the tags alone.
• Keep it short. The caption sits over a moving image; a headline and one line reads far better than a paragraph.

Adding a link or a button

<figcaption class="rf-text">
  <h2>Autumn collection</h2>
  <p>Twenty-two pieces, cut in Florence.</p>
  <p><a href="/collections/autumn">See the collection</a></p>
</figcaption>

Links and buttons inside a caption stay clickable and keyboard-reachable — dragging the slider will not fire them by accident, and tabbing reaches them in the usual order.

06 Add or remove a slide

Slides appear in the order they are written. To add one, copy an entire <figure class="rf-slide">…</figure> block — opening tag to closing tag — paste it where you want it, and change the image and text. To remove one, delete the whole block. To reorder, move blocks around.

<div data-refrakt="atelier">

  <figure class="rf-slide">  <!-- slide 1 -->
    <img src="img/one.jpg" alt="…">
  </figure>

  <figure class="rf-slide">  <!-- slide 2 — copy this whole block to add another -->
    <img src="img/two.jpg" alt="…">
  </figure>

</div>

Nothing else needs updating. Dots, counters and the progress bar all count the slides themselves, so five figures give you five dots automatically.

07 Pick a different look

Every optical character — how deep the glass ribs run, how far colour splits when you drag, where the light sits, whether there is film grain — is bundled into a named preset. Switching between them means changing one word.

Find the container element that wraps your slides. It carries a data-refrakt attribute:

<div data-refrakt="atelier">

Change the word in the quotes. That is the whole operation.

<div data-refrakt="darkroom">

The eight looks

Want to feel what each control does before choosing? Open the optics-lab demo and drag the sliders. Every knob there is one of the settings in the reference, and the panel shows you the exact line to copy for whatever you land on.

08 Put it on your own page

Working inside a copied demo is the fastest way to start. When you are ready to move the slider into your own site, here is the entire recipe.

1. Copy two files. Take refrakt.umd.js and refrakt.css out of refrakt/dist/ and put them next to your page — or in whatever assets or js folder you already use.

2. Link the stylesheet in your <head>.

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

3. Write your slider markup wherever you want it on the page.

4. Add the script tag at the end of your <body>. Nothing else — no initialisation code, no $(document).ready.

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

Here is a complete, working page. Copy it into a file called index.html, put three photos beside it in an img folder, and open it in a browser:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My slider</title>
  <link rel="stylesheet" href="refrakt.css">
  <style>
    body { margin: 0; }
    #hero { height: 70vh; }   /* the slider fills whatever box you give it */
  </style>
</head>
<body>

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

    <figure class="rf-slide">
      <img src="img/one.jpg" alt="Fishing boats at dawn">
      <figcaption class="rf-text">
        <h2>Harbour, 5 a.m.</h2>
        <p>The fleet goes out before the light does.</p>
      </figcaption>
    </figure>

    <figure class="rf-slide">
      <img src="img/two.jpg" alt="Nets drying on the quay">
      <figcaption class="rf-text">
        <h2>Mending day</h2>
        <p>Every third Tuesday, the whole quay smells of tar.</p>
      </figcaption>
    </figure>

    <figure class="rf-slide">
      <img src="img/three.jpg" alt="The lighthouse in fog">
      <figcaption class="rf-text">
        <h2>Fog signal</h2>
        <p>Two blasts every ninety seconds, since 1904.</p>
      </figcaption>
    </figure>

  </div>

  <script src="refrakt.umd.js"></script>
</body>
</html>

Four rules, and there are no others

09 If something looks wrong

Five things account for nearly every first-hour problem. Check these before anything else:

The quickest diagnosis is always the browser console. Press F12 (or ⌥⌘I on a Mac) and read the Console tab. Refrakt announces every problem it detects there, prefixed with [Refrakt], in plain sentences — a mistyped option, an image that failed to load, a missing alt. It never fails silently, and it never throws an exception at you: a bad setting produces a different look, not a broken page.

The Troubleshooting page has the long version — every warning the engine can emit, what causes it, and what to do about it.

10 Where to go next

You now have your own pictures and your own words in a slider whose character you chose. Everything past this point is optional.