@hsal/paper

Pages you turn by folding the corner

A JavaScript library for a stack of paper pages with a dog-ear in the corner. Drag it past the middle and the page folds over to the back. It also makes books, where a leaf curls over the spine.

npm install @hsal/paper
  • 21.5 kB of JavaScript and 8.4 kB of CSS, gzipped
  • No dependencies
  • Components for 5 frameworks, plus <paper-stack> and <paper-book>
  • A scroll-snap carousel when JavaScript is off

A page is any element

This one is a <section> with a heading and a paragraph. The stack makes a page of each child of its root.

1 of 5

Each page can have its own paper

This page sets its surface to blue. Fold the corner and the back of the flap is blue too.

2 of 5

Turned pages pile up above

Their edges show along the top. Grab the folded-back corner at the top left and drag to bring the last one back.

3 of 5

Other ways to turn

  • Focus the stack and press ← or →
  • Scroll sideways with a wheel or a trackpad
  • Swipe with a finger or a pen
  • Call next() or prev()

4 of 5

The last page wraps around

Turn this one and the first page comes back. Set wrap to false to stop here instead.

5 of 5

Five pages in a <PaperStack> from @hsal/paper/astro. The dog-ear rests at its default size, 2 cm by 1 cm, the same as the squares on the mat.

A book, two pages at a time

In book mode you drag a page corner across the spine and the leaf curls over, with its back showing as it comes. This one is a <PaperBook> with display="double" and hard covers, so the first and last leaves swing like boards. Focus it to turn with the arrow keys, or with Home and End for the covers.

Five folds

In the notation origami diagrams use

Valley fold

Fold the paper toward you, so the crease sinks like a valley. Diagrams draw it as a dashed line.

1

Mountain fold

Fold it away from you, so the crease stands up like a ridge. The line is a dash and two dots.

2

Inside reverse fold

Push a corner in between its two layers and flatten it. A crane gets its head this way.

3

Squash fold

Lift a flap, open it and press it flat into a new shape. A hollow arrowhead means push here.

4

Dog-ear

Fold a corner of the page over the page. Every front page in a stack rests like this, 2 cm along the bottom and 1 cm up the side.

5

Colophon

This book is a PaperBook from @hsal/paper/astro, eight pages long. The diagrams are inline SVG and the type is Archivo and Literata.

Turn this page for the back cover, or press Home for the front.

6

paper.hsal.es

Try the options

Options have no live setters. A change here destroys the controller and calls createPaper again on the same markup, at the page you were on. The code under the paper is the call it makes.

The options need JavaScript. With it off, the playground's stack and book are the carousels the no-script styles make.

Mode
Interactions
Stack
Book
Motion

1

Drag the dog-ear

2

Press the arrow keys

3

Scroll sideways

4

Swipe with a finger

5

Use the buttons

The call

createPaper(root);

paper.state

{}

Events

Turn a page anywhere on this page and its paper:* events land here, newest first.

    Restyle it with custom properties

    The look is CSS custom properties, set anywhere above the stack. Move the controls and the stack below takes the values, then refresh() measures its lengths again. Turn a page or two to see the folded-back corner.

    Paper and ink

    --paper-sheet is the paper. --paper-ink draws the focus ring and the arrows on the flap.

    The dog-ear

    --paper-fold-rest-x and -y size the corner at rest. Centimetres keep it the same size on any screen.

    The fan

    --paper-splay turns each page under this one a little further, by the log of its place.

    .stack {
    }

    Use it from your framework

    One package, with an entry point for each of 5 frameworks and the custom elements for everything else. Each framework is an optional peer dependency, so you install only @hsal/paper.

    React

    React 19, marked as a client module. Each child element is a page. The ref is the controller, and usePaper gives you the controller and its state.

    npm install @hsal/paper
    Notes.tsx
    import { PaperStack, usePaper } from '@hsal/paper/react';
    import '@hsal/paper/styles.css';
    
    export function Notes({ days }: { days: Day[] }) {
      const paper = usePaper();
      return (
        <>
          <PaperStack ref={paper.ref} label="Field notes" wrap={false} onChange={(detail) => console.log(detail.index)}>
            {days.map((day) => <section key={day.id}><h2>{day.title}</h2></section>)}
          </PaperStack>
          <p>Page {(paper.state?.index ?? 0) + 1} of {days.length}</p>
        </>
      );
    }

    Vue

    Vue 3.3 and later, as compiled render functions, so your bundler needs no loader. Each element of the default slot is a page, v-for included. The callbacks are the events turn-start, turn-end, change and settle.

    npm install @hsal/paper
    Atlas.vue
    <script setup lang="ts">
    import { PaperBook, usePaper } from '@hsal/paper/vue';
    import '@hsal/paper/styles.css';
    
    defineProps<{ plates: Plate[] }>();
    const { ref: book, state } = usePaper<'book'>();
    </script>
    
    <template>
      <PaperBook :ref="book" label="Atlas" display="double" @change="(detail) => console.log(detail.spread)">
        <section v-for="plate in plates" :key="plate.id"><h2>{{ plate.title }}</h2></section>
      </PaperBook>
      <p>Spread {{ state?.spread }}</p>
    </template>

    Svelte

    Svelte 5. A snippet can't be split into elements, so the pages come from a page snippet that runs once per index up to pageCount. controller and state are bindable.

    npm install @hsal/paper
    Notes.svelte
    <script lang="ts">
      import { PaperStack, type PaperStackState } from '@hsal/paper/svelte';
      import '@hsal/paper/styles.css';
    
      let { days }: { days: Day[] } = $props();
      let sheet: PaperStackState | null = $state(null);
    </script>
    
    <PaperStack label="Field notes" pageCount={days.length} bind:state={sheet} onChange={(detail) => console.log(detail.index)}>
      {#snippet page(index)}
        <section><h2>{days[index].title}</h2></section>
      {/snippet}
    </PaperStack>

    Solid

    Solid 1.8 and later. Solid 2's compiler plugins don't take the package yet. Each child element is a page, and ref gets each controller made, then null when it goes.

    npm install @hsal/paper
    Atlas.tsx
    import { For } from 'solid-js';
    import { PaperBook, usePaper } from '@hsal/paper/solid';
    import '@hsal/paper/styles.css';
    
    export function Atlas(props: { plates: Plate[] }) {
      const book = usePaper<'book'>();
      return (
        <>
          <PaperBook ref={book.ref} label="Atlas" hardCovers onSettle={(detail) => console.log(detail.spread)}>
            <For each={props.plates}>{(plate) => <section><h2>{plate.title}</h2></section>}</For>
          </PaperBook>
          <p>Spread {book.state()?.spread}</p>
        </>
      );
    }

    Astro

    Astro 5 and later. The components import the stylesheet and start the script themselves. Options with a data-paper-* attribute are props. For the rest, listen for the paper:* events on the root, or get the controller with paperOf from @hsal/paper/astro/client.

    npm install @hsal/paper
    Sheets.astro
    ---
    import { PaperStack } from '@hsal/paper/astro';
    import Sheet from '../components/Sheet.astro';
    
    const sheets = [{ title: 'Monday' }, { title: 'Tuesday', surface: '#1f4f8f' }];
    ---
    
    <PaperStack label="Sheets" pageCount={sheets.length} surfaces={sheets.map((sheet) => sheet.surface)}>
      {(index: number) => <Sheet title={sheets[index].title} />}
    </PaperStack>

    HTML

    No build step. <paper-stack> and <paper-book> are custom elements, and their options go in data-paper-* attributes. The data-paper-stack attribute styles the carousel before the element loads.

    npm install @hsal/paper
    index.html
    <link rel="stylesheet" href="https://unpkg.com/@hsal/paper/dist/styles.css">
    <script type="module" src="https://unpkg.com/@hsal/paper/dist/element.js"></script>
    
    <paper-stack data-paper-stack aria-label="Field notes" style="aspect-ratio: 2 / 1">
      <section><h2>Monday</h2><p>…</p></section>
      <section data-paper-surface="#1f4f8f"><h2>Tuesday</h2><p>…</p></section>
      <section><h2>Wednesday</h2><p>…</p></section>
    </paper-stack>

    Without JavaScript

    The components send finished HTML, so the pages can be read before any script runs, or if none runs. With scripting off, a media query in the stylesheet turns the stack into a scroll-snap row, with the pages under it drawn as two edges, and the book into a row of spreads. Chrome adds arrows and dots with ::scroll-button() and ::scroll-marker. Other browsers show the edge of the next page.

    The frame below is a page in a sandbox that doesn't allow scripts, so it is what a reader with JavaScript off gets.