Web components
for e-ink & e-paper.

What EPaper is

EPaper is an open-source library of e-ink web components: 81 vanilla custom elements built for electrophoretic (e-ink, also spelled eink) panels rather than backlit screens. Every element is plain HTML — <e-button>, <e-table>, <e-date-picker> — so an e-paper dashboard, an electronic shelf label or a meeting-room display is written the way a web page is written, with no framework and no build plugin.

Web components suit e-ink precisely because the platform does the work. A custom element owns the DOM it renders, so it can patch a single text node when a value changes instead of rebuilding a subtree — and on an e-paper panel the size of that change is the cost of the refresh. Every component here is written to that constraint, and the ones that take input participate in <form> natively through ElementInternals.

None of it requires an e-ink device. The components render normally on any screen; the constraints the medium imposes — no animation, no hover, high contrast — simply produce a stark, print-like interface that also suits kiosks, embedded panels and low-distraction reading UIs.

What makes a web component e-ink-ready

No animations, no transitions

An e-paper controller redraws in discrete waveform cycles, not frames. A 300 ms fade is not a gradient on e-ink — it is a few dozen full-region refreshes queued faster than the panel can drain them. base.css resets both globally inside .ink-page.

No :hover states

E-ink devices are touch- or button-driven and have no pointer, so anything hidden behind :hover is unreachable. State is carried by :focus-visible, [aria-selected], [aria-checked] and [data-active] instead.

Surgical DOM updates

Components patch text nodes and attributes in place and compare before writing, keeping the damaged rectangle small enough for the controller to pick a fast partial refresh over a full GC16 flash. See how partial refresh works.

No Shadow DOM

Light DOM only, themed through one layer of CSS custom properties, so a panel vendor can restyle the whole set without touching JavaScript — and so a crawler reads the text without traversing a shadow root.

All six design principles →

Install it

npm install @marcomattes/epaper-components

// Side-effect import registers all custom elements.
import '@marcomattes/epaper-components';
import '@marcomattes/epaper-components/styles/tokens.css';
import '@marcomattes/epaper-components/styles/base.css';
import '@marcomattes/epaper-components/styles/components.css';

Quickstart, including pnpm and yarn →

81 components, one custom element each

Buttons, inputs, pickers, tables, calendars and layout primitives — each a standalone module, so a page that needs one component ships one component. The form controls are form-associated: they submit through FormData and validate through ElementInternals like native inputs do.

How to build for e-ink

Long-form explanations of the medium and the platform APIs underneath it. They are useful whether or not you install EPaper.

• How partial refresh works An electrophoretic display redraws in discrete waveform modes, not in frames. This guide explains GC16, GL16, DU and A2, why ghosting happens, how the damaged rectangle is computed, and what all of that means for the DOM you write.
• Web components without Shadow DOM Shadow DOM is optional. This guide covers what encapsulation actually buys, the real costs — cross-root ARIA, styling friction, SSR and form participation — and how a light-DOM component library stays maintainable without it.
• Form-associated custom elements How to make a custom element participate in <form>, FormData and constraint validation using ElementInternals: setFormValue, setValidity, the four form lifecycle callbacks, and the pitfalls that are not in the specification summary.
• Designing for e-ink Practical interface rules for electrophoretic displays: why hover states cannot exist, how to signal state without colour or motion, typography that survives a 1-bit render, and what changes on colour e-paper.

Complete builds: An e-ink status dashboard An electronic shelf label A meeting room display An e-paper weather station

Common questions

All 25 answers →