# Slab, in full > Slab is a headless Web Component library, published as `slab-elements`. Each element handles the hard parts — keyboard and focus, ARIA, form participation, events — on top of the native element it maps to. What it looks like is up to you: style it from the outside with `::part()` and `:state()`, or subclass it and make it your own. Every page of the docs at https://slab-elements.dev/, as Markdown, in one file. [llms.txt](https://slab-elements.dev/llms.txt) is the short version, with a link to each page instead. --- Source: https://slab-elements.dev/index.md # Slab > Slab is a headless Web Component library, published as `slab-elements`. Each element handles the hard parts — keyboard and focus, ARIA, form participation, events — on top of the native element it maps to. What it looks like is up to you: style it from the outside with `::part()` and `:state()`, or subclass it and make it your own. ## Why headless - **Bring your own design.** Slab doesn't ship a single line of visual CSS. No theme to fight, nothing to override. Every piece you'd want to style is a `::part()`, and every state you'd react to is a `:state()`. - **The platform first.** A Slab dialog is a ``. A disclosure is a `
`. A switch is a checkbox. Slab leans on what browsers already do well and only fills in what's missing. Attributes in, events out. - **Built to last.** Custom elements are a web standard, not a framework feature, so they work in React, Vue, Svelte, Ember, Rails, or plain HTML — and in whatever you're using three years from now. ## One element, any look Every Slab element ships with no visual CSS, so the same `` can be a plain checkbox, a hard-edged brick, a rounded pill, or anything else, with nothing but CSS from the outside. For example, a rounded pill: ```css slab-switch::part(input) { appearance: none; background: #767676; block-size: 1.7rem; border-radius: 999px; inline-size: 3rem; } slab-switch:state(checked)::part(input) { background: #2563eb; } ``` That's what headless means: Slab handles how it works, and you decide how it looks. ## Usage ```sh pnpm add slab-elements lit ``` `lit` is a peer dependency. Import each element you use, which registers it, with any bundler, or an import map, resolving the imports: ```html Poured once, built on forever. ``` Nothing's styled until you style it. Every piece you'd want to reach is a `::part()`, and every state you'd want to react to is a `:state()`: ```css slab-disclosure::part(summary) { font-weight: 600; } slab-disclosure[open]::part(summary) { color: #b3381a; } ``` Want to go further? Subclass an element, set `styles`, and register it under a tag of your own. Its functional styles stick around underneath yours: ```js import Disclosure from 'slab-elements/disclosure.js'; import { css } from 'lit'; customElements.define( 'acme-disclosure', class extends Disclosure { static styles = css` [part~='summary'] { font-weight: 600; } `; }, ); ``` ## 60 elements Every one has its own page. [Components](https://slab-elements.dev/components.md) lists them all, grouped. - **Overlays:** [Alert](https://slab-elements.dev/components/alert.md), [Alert Dialog](https://slab-elements.dev/components/alert-dialog.md), [Command Palette](https://slab-elements.dev/components/command-palette.md), [Dialog](https://slab-elements.dev/components/dialog.md), [Drawer](https://slab-elements.dev/components/drawer.md), [Hover Card](https://slab-elements.dev/components/hover-card.md), [Popover](https://slab-elements.dev/components/popover.md), [Toast](https://slab-elements.dev/components/toast.md), [Tooltip](https://slab-elements.dev/components/tooltip.md) - **Disclosure:** [Accordion](https://slab-elements.dev/components/accordion.md), [Carousel](https://slab-elements.dev/components/carousel.md), [Disclosure](https://slab-elements.dev/components/disclosure.md), [Splitter](https://slab-elements.dev/components/splitter.md) - **Navigation:** [Breadcrumb](https://slab-elements.dev/components/breadcrumb.md), [Context Menu](https://slab-elements.dev/components/context-menu.md), [Menu](https://slab-elements.dev/components/menu.md), [Menubar](https://slab-elements.dev/components/menubar.md), [Navigation Menu](https://slab-elements.dev/components/navigation-menu.md), [Pagination](https://slab-elements.dev/components/pagination.md), [Steps](https://slab-elements.dev/components/steps.md), [Tabs](https://slab-elements.dev/components/tabs.md), [Toolbar](https://slab-elements.dev/components/toolbar.md), [Tree](https://slab-elements.dev/components/tree.md) - **Selection:** [Combobox](https://slab-elements.dev/components/combobox.md), [Listbox](https://slab-elements.dev/components/listbox.md), [Select](https://slab-elements.dev/components/select.md), [Toggle Button](https://slab-elements.dev/components/toggle-button.md), [Toggle Group](https://slab-elements.dev/components/toggle-group.md) - **Form:** [Checkbox](https://slab-elements.dev/components/checkbox.md), [Checkbox Group](https://slab-elements.dev/components/checkbox-group.md), [Color Picker](https://slab-elements.dev/components/color-picker.md), [Copy Button](https://slab-elements.dev/components/copy-button.md), [Date Field](https://slab-elements.dev/components/date-field.md), [Date Picker](https://slab-elements.dev/components/date-picker.md), [Date Range Field](https://slab-elements.dev/components/date-range-field.md), [Date Range Picker](https://slab-elements.dev/components/date-range-picker.md), [Editable](https://slab-elements.dev/components/editable.md), [Field](https://slab-elements.dev/components/field.md), [File Drop](https://slab-elements.dev/components/file-drop.md), [Form](https://slab-elements.dev/components/form.md), [Number](https://slab-elements.dev/components/number.md), [Password Field](https://slab-elements.dev/components/password-field.md), [Pin Input](https://slab-elements.dev/components/pin-input.md), [Radio Group](https://slab-elements.dev/components/radio-group.md), [Range Slider](https://slab-elements.dev/components/range-slider.md), [Rating](https://slab-elements.dev/components/rating.md), [Search Field](https://slab-elements.dev/components/search-field.md), [Slider](https://slab-elements.dev/components/slider.md), [Switch](https://slab-elements.dev/components/switch.md), [Tags Input](https://slab-elements.dev/components/tags-input.md), [Text Field](https://slab-elements.dev/components/text-field.md), [Textarea](https://slab-elements.dev/components/textarea.md), [Time Field](https://slab-elements.dev/components/time-field.md) - **Data:** [Calendar](https://slab-elements.dev/components/calendar.md), [Feed](https://slab-elements.dev/components/feed.md), [Grid List](https://slab-elements.dev/components/grid-list.md), [Meter](https://slab-elements.dev/components/meter.md), [Progress](https://slab-elements.dev/components/progress.md), [Sortable List](https://slab-elements.dev/components/sortable-list.md), [Table](https://slab-elements.dev/components/table.md) --- Source: https://slab-elements.dev/get-started.md # Get started > Install Slab, import the elements you use, and make them yours. Everything you need, in order. ## Install it Slab is one package, `slab-elements`, with Lit as a peer dependency. ```sh pnpm add slab-elements lit ``` ## Import what you use Each element is its own module, and importing it registers its tag. Import the ones you use, and nothing else ships. An element made of parts, like Tabs, has a module for each part. ```js import 'slab-elements/switch.js'; import 'slab-elements/tabs.js'; import 'slab-elements/tabs.tab.js'; import 'slab-elements/tabs.panel.js'; ``` Any bundler resolves the imports, or an import map does without one. ## Use it like a native element Attributes in, events out, the same as every built-in element. The events are the ones its native element fires, like "change", "input" and "toggle", and they bubble, so you can listen higher up too. ```html ``` Every control needs a `label`, and one without throws rather than going unnamed. `hide-label` hides it from view and keeps it for screenreaders. Like a native control, the `checked` and `value` attributes are where it starts, and the properties are where it is now. ## In your framework There's no wrapper package. The tag is the component, in React, Vue, Svelte, Ember, Rails, or plain HTML. React 19 and Svelte listen for an event through `on` and its exact name, such as `onchange` or `oncopy-error`, Ember's `{{on}}` takes the exact name too, and Vue needs to know which tags are custom elements. The [home page](https://slab-elements.dev/index.md#usage) shows the same Disclosure in each. ```js import vue from '@vitejs/plugin-vue'; export default { plugins: [ vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('slab-'), }, }, }), ], }; ``` ## On the server Using Next.js, Nuxt, SvelteKit, Astro, Ember or Rails? You're good. Importing an element on the server is safe. Slab doesn't render there, though. The tag is sent as you wrote it, and the element takes over in the browser once its module loads. One thing to watch: that module has to reach the browser. With server components, import it from a client one. ```js 'use client'; import 'slab-elements/switch.js'; export default function Notifications() { return ; } ``` Before an element is defined, there's nothing of it to see. Use `:not(:defined)` to hold its space, or to hide what's slotted into it, until it's ready. ## Put it in a form Slab's controls are form-associated, so they work in a plain `
` the way an `` does. They submit their `name` and `value`, reset with the form, and come back when the browser restores the page. Validation is the native element's too: `required`, `pattern` and the rest mean what they mean on an ``, and `checkValidity()`, `reportValidity()` and `setCustomValidity()` work the same. ```html
``` There's a [``](https://slab-elements.dev/components/form.md) too, if you'd like the form itself to be a Slab element. ## Style it Nothing ships styled, so an element has no size and nothing to see until you give it one. Reach its pieces with `::part()` and its conditions with `:state()`. Every component's page lists both. ```css slab-checkbox::part(checkbox) { block-size: 1rem; border: 1px solid currentcolor; inline-size: 1rem; } slab-checkbox:state(checked)::part(checkbox) { background-color: currentcolor; } ``` ## Make it your own To go further, subclass it, set `styles`, and register it under a tag of your own. Slab's functional styles, like a label that's hidden but still read, survive yours. ```js import Checkbox from 'slab-elements/checkbox.js'; import { css } from 'lit'; customElements.define( 'acme-checkbox', class extends Checkbox { static styles = css` /* ... */ `; }, ); ``` Every [component's page](https://slab-elements.dev/components.md) has a styled version to start from, with its source to copy and change. ## Your words, in any language Slab brings little text of its own. Where an element has to make some, mostly names for screenreaders, it's English until you translate it. Register your language's words once, and every element whose nearest `lang` is that language uses them. "fr-CA" takes "fr" for anything it leaves out, and English after that. Text built from a value, like Pagination's "Page 3", is a function, so you can word and order it for your language. ```js import { registerStrings } from 'slab-elements/strings.js'; registerStrings('de', { alertDismiss: 'Schließen', paginationPage: (page) => `Seite ${page}`, }); ``` `Strings` lists every one. An attribute or property on an element, like Alert's `dismiss-label`, still wins, for the one place you want different words. ## TypeScript The types come with the package. Each element adds its tag to `HTMLElementTagNameMap`, so `document.querySelector('slab-switch')` is typed as Slab's `Switch`. For your templates, import your framework's types once, and every tag's properties are checked, so a misspelled `hideLabel` or a wrong `orientation` is a type error. ```ts // React. Or 'slab-elements/svelte.js' for Svelte 5, // 'slab-elements/vue.js' for Vue, or 'slab-elements/ember.js' // for Ember with Glint. import type {} from 'slab-elements/react.js'; ``` Events are typed too: a handler such as `oncopy-error` in React and Svelte, `@copy-error` in Vue, or `{{on "copy-error"}}` in Ember, gets the event with the element as its `currentTarget`. In Ember, Glint checks the attributes of each tag, by their names in HTML, such as `hide-label`. For any other framework, `slab-elements/jsx.js` has `SlabElementProps`, every tag and its properties, and `SlabElementEvents`, every tag and its events. ## In your editor Slab comes with what editors need to autocomplete its tags in plain HTML. Type `` submits, validates and resets them. No extra wiring needed. - **What you already know.** Events, methods and validation work the way native elements do. If you know `` and ``, you know Slab. - **Only what you import.** Each element is its own module and only a few kilobytes. See [What it weighs](https://slab-elements.dev/get-started.md#size) for the numbers. It's not all free, though. An element is empty markup until its script runs, where a React library can render on the server. Slab needs the [browsers](https://slab-elements.dev/get-started.md#browsers) above, with no fallbacks for older ones. And you style through `::part()` and `:state()` rather than class names, so utility classes reach an element's host and what you slot into it, but not its insides. --- Source: https://slab-elements.dev/upgrade.md # Upgrade to 1.0 > Every change since 0.1 that can break something, and what to change for it. ## Before you start Each section names the elements it touches and the release it came in. Skip any whose elements you don't use, and any from a release you're already past. After upgrading, run your type checker: most of these changes show up there first, as an unknown attribute, property or event. ```sh pnpm add slab-elements@^1.0.0 ``` ## Focus rings on Range Slider, Color Picker and Splitter From 0.2 and 0.3. Range Slider's and Color Picker's thumbs and Splitter's separator each hold a visually hidden range input, which is what's focused, so they no longer match `:focus-visible` themselves. Style the ring through the `focus-visible` part each one gains while its input has a visible focus. ```css /* Before */ slab-range-slider::part(start):focus-visible { outline: 2px solid; } /* After. The same for Color Picker's hue-thumb and Splitter's separator. */ slab-range-slider::part(start focus-visible) { outline: 2px solid; } ``` ## Tooltip and Hover Card's "toggle" Every element with `open` now dispatches "toggle" as a `ToggleEvent` with `oldState` and `newState`, the way a popover does. Like a popover's, it doesn't bubble and isn't composed. Tooltip and Hover Card's used to bubble, so a listener on an ancestor no longer hears them. Listen on the element itself. ```js // Before document.addEventListener('toggle', onToggle); // After tooltip.addEventListener('toggle', (event) => { console.log(event.newState); // "open" or "closed" }); ``` Menu, Context Menu, Select and Combobox dispatch "toggle" too, for the first time, which needs no change. ## Grid List's selection `selection-mode` is gone. `selectable` makes rows selectable one at a time, and `multiple` makes them selectable more than one at a time, the same `multiple` as Listbox, Select, Combobox and Tree. ```html ``` ## Checkbox Group's values The list of checked values moves from `value` to `values`, as on Listbox, Select, Combobox, Tags Input and Toggle Group. `value` is now a string, the first checked value, and setting it checks only that Checkbox. What's submitted with a form doesn't change. ```js // Before const checked = group.value; // ['forms', 'rebar'] group.value = ['forms']; // After const checked = group.values; // ['forms', 'rebar'] group.values = ['forms']; ``` ## Password Field's "reveal-change" The show-and-hide button dispatches "reveal-change" instead of "toggle", since "toggle" is now the `ToggleEvent` of elements with `open`. Read `revealed` in the handler for whether the password shows. ```js // Before field.addEventListener('toggle', onReveal); // After field.addEventListener('reveal-change', () => { console.log(field.revealed); }); ``` ## Toast's "dismiss" "dismiss" can now be canceled to keep the toast shown, as Alert's can, so it's dispatched before the toast hides rather than after. In a listener, `open` is still `true`. Code that read `open` there to see that the toast had closed should wait for it instead, or drop the check. ```js toast.addEventListener('dismiss', (event) => { if (hasUnsavedChanges()) { event.preventDefault(); // It stays shown. } }); ``` ## Opening Dialog, Alert Dialog and Command Palette These now open the way a `` does. `showModal()`, which is new, opens them as a modal. `show()` and setting `open` now open them non-modally: there's no backdrop, the rest of the page stays usable, and Escape only closes them with `closedby`. Where you set `open` for a modal, add `modal`, which makes `open` open it as a modal. That's also how a framework that binds `open` gets one. Where you called `show()` for a modal, call `showModal()`. Drawer opens non-modally as before, and takes `modal` and `showModal()` too. ```html … … ``` `dialog.show()` for a modal becomes `dialog.showModal()`. ## Date Picker's and Date Range Picker's `showPicker()` `showPicker()` now throws as a native input's does: a "NotAllowedError" when it isn't called from a user gesture, such as a click or a key press, and an "InvalidStateError" while it's disabled or read-only. It used to open the calendar from anywhere, and do nothing while disabled. Call it from an event handler, or set `open` to open the calendar from code. ```js // Before picker.showPicker(); // After, from code picker.open = true; // After, from a click button.addEventListener('click', () => picker.showPicker()); ``` ## Checkbox's `indeterminate` `indeterminate` is now a property only, with no attribute, as on a native checkbox, and a form's reset leaves it as it is, as it does natively. Set the property from script, or bind it as a property in a framework, such as `.indeterminate` in Lit. ```html ``` ## Subclasses The protected hooks Slab's own styled subclasses override, such as Dialog's `renderContent()` and Date Field's `renderControl()`, and every element's `version`, are marked `@internal`. They're out of the published types, so a subclass that overrides a hook with `override` no longer type checks. They were never public API and can change in any release. Subclassing an element to set `styles` is public and keeps working. What's public from 1.0, and what isn't, is in [What you can count on](https://slab-elements.dev/get-started.md#api). --- Source: https://slab-elements.dev/accessibility.md # Accessibility > What Slab does for accessibility, how it's tested, and what hasn't been checked yet. ## What Slab does Each element is built on the native element it corresponds to, so it gets that element's semantics from the platform instead of rebuilding them in ARIA. Slab adds what the platform doesn't have: keyboard and focus handling, ARIA where no native element fits, labels and descriptions wired to the right element, validation messages, and announcements for changes that aren't otherwise read out. ## What every change is tested for Every change runs the whole suite in the latest Chromium, Firefox and WebKit. Axe checks every element for known violations. ARIA snapshot tests pin down each element's roles, names and states, so any change to them shows up in review. Keyboard tests cover what each element does with the keyboard, including in right-to-left layouts, and some elements also have tests for forced colors and reduced motion. ## What's been checked beyond that In October 2026, every element's semantics, keyboard support and announcements were audited, mostly by reading Chromium's accessibility tree, and everything found was fixed. That covered things like forced colors, right-to-left arrow keys, typing with an input method editor, validation messages and live announcements. ## What's been checked by hand In November 2026, the 21 elements most likely to go wrong were walked through with VoiceOver on macOS in Chrome, step by step: the composite ones, like Combobox, Menu, Tree and Calendar, and the ones that announce changes, like Toast and Tags Input. The nine riskiest were also walked through in Safari: Combobox, Select, Listbox, Menu, Tree, Calendar, Command Palette, Slider and Range Slider. Most did what they should, and the gaps it found have been fixed. That was done to the best of our ability by people who build components, not by accessibility specialists or people who rely on a screen reader every day. ## What hasn't been checked yet The other 12 of those 21 haven't been checked in Safari yet. NVDA, JAWS and TalkBack haven't been tried, and neither have voice control or switch access. The rest, which lean more on their native elements, haven't been checked by hand. Automated tools catch only some problems, and screen readers differ from each other and from the accessibility tree a browser builds. ## What's up to you Slab is headless, so how an element looks is yours, and so is much of whether it's accessible: color contrast, a visible focus ring, target sizes, and text that says what a control does. Slab is a set of building blocks, so whether your app meets WCAG depends on how you use and style them. ## Tell us what you find If an element doesn't work with your assistive technology, please [open an issue](https://github.com/ynotdraw/slab-elements/issues/new?template=accessibility.yml) with what you used and what you heard. Pull requests are welcome too. --- Source: https://slab-elements.dev/llms.md # LLMs and agents > Teach your coding agent Slab with the skill in the package, and point any LLM at these docs as Markdown. ## Why bother? Ask an agent for a Select and it'll often reach for a React library's API: an `onChange` prop, an `isOpen`, a controlled `value`. Slab has none of that. It works like a native element, and the agent writes better code when it knows that. So Slab ships with what it needs to know. ## Add the skill Slab comes with an [agent skill](https://agentskills.io/), a folder of instructions your agent reads when it's working with Slab. It works with Claude Code, Cursor, Codex, GitHub Copilot and the rest of the agents that read skills. Add it with one command from your project. ```sh npx skills add ynotdraw/slab-elements --skill slab ``` It asks which agents to add it to, and puts it where each one looks. Add `-g` to add it for all your projects. ## Or copy it from the package The skill is in the package too, at `skills/slab`, so the one you copy matches the version you've installed. That command takes it from GitHub instead, so it's the latest. Copy it into wherever your agent looks for skills, such as `.claude/skills` for Claude Code, and copy it again after you upgrade. ```sh mkdir -p .claude/skills cp -R node_modules/slab-elements/skills/slab .claude/skills/ ``` ## What's in it The advice is written by hand. The reference is built from Slab's own source each release, so it can't drift from the code. - **Picking a component.** Every component, grouped as on this site, with the native element it's built on and what it's for. - **The native way.** Attributes in, events out, `label` on every control, `showModal()`, `multiple` and `values`, and the rest of what makes Slab work like the platform. - **Forms, styles and frameworks.** Form association and validity, `::part()` and `:state()`, subclassing, React 19, Vue, Svelte, Ember and server rendering. - **A page per component.** Its imports, usage and keyboard, and every attribute, property, method, event, slot, part and state, from `custom-elements.json`. It also says what not to do. Don't add `role` or `aria-*` to fix an element, don't invent attributes, and don't test in jsdom. ## llms.txt Using a chat rather than an agent? [llms.txt](https://slab-elements.dev/llms.txt) follows the [llms.txt proposal](https://llmstxt.org/): a short summary of Slab, then a link to every page on this site with a line about each. Hand it to an LLM and it can find the page it needs. Is your tool one that doesn't follow links? [llms-full.txt](https://slab-elements.dev/llms-full.txt) is every page on this site in one file, so it has the whole thing at once. It leaves out the styled examples' source, but it's still big, so save it for tools that can't fetch pages. ## Every page as Markdown Each page here has a Markdown twin with the same content, at the same address ending in `.md`, like [Get started's](https://slab-elements.dev/get-started.md). Every guide and component page has a **Copy page** button under its title for pasting into a chat, and a link to view it. ## Let your tools check the work Agents still make mistakes. Your type checker catches a lot of them. Import your framework's types once, as [TypeScript](https://slab-elements.dev/get-started.md#typescript) shows, and a made-up attribute or a misspelled event is an error before it ships. Your editor can autocomplete Slab's tags and attributes in plain HTML too, once it's [set up](https://slab-elements.dev/get-started.md#editors). Tools that read custom elements can use `slab-elements/custom-elements.json`, the manifest the skill is built from. --- Source: https://slab-elements.dev/components.md # Components > All of Slab's headless Web Components. Every one is built on a native element, or an ARIA role when the platform doesn't have one. ## Overlays - [Alert](https://slab-elements.dev/components/alert.md): ``, built on `[role=alert]`. An inline message that gets announced when it shows up. Put it on the page empty, then fill it in when there's something to say. - [Alert Dialog](https://slab-elements.dev/components/alert-dialog.md): ``, built on ``. A modal dialog that asks before something can't be undone. Focus starts on Cancel, and a click outside doesn't close it. - [Command Palette](https://slab-elements.dev/components/command-palette.md): ``, built on ` + `. A search for commands, opened as a modal with `showModal()`: type to filter a list of Options, then Enter runs the best match. It's a Combobox in a Dialog. - [Dialog](https://slab-elements.dev/components/dialog.md): ``, built on ``. A dialog built on the native ``, modal or not. A modal one keeps focus inside, closes on Escape, and makes the rest of the page inert — the platform does the heavy lifting. - [Drawer](https://slab-elements.dev/components/drawer.md): ``, built on ``. A dialog for a side panel. Non-modal by default, so the page behind it stays usable, or modal through `showModal()`. - [Hover Card](https://slab-elements.dev/components/hover-card.md): ``, built on `[popover]`. A preview of what a link leads to, shown beside it on hover and keyboard focus, with room for links and buttons of its own. - [Popover](https://slab-elements.dev/components/popover.md): ``, built on `[popover]`. Content that pops up beside the element that opened it, in the top layer, and gets dismissed the way a native popover does. - [Toast](https://slab-elements.dev/components/toast.md): ``, built on `[role=status]`. A polite heads-up that something just happened. It lives on the page up front, so screen readers actually hear it. - [Tooltip](https://slab-elements.dev/components/tooltip.md): ``, built on `[role=tooltip]`. A short description that shows up beside an element on hover and focus. ## Disclosure - [Accordion](https://slab-elements.dev/components/accordion.md): ``, built on `group of
`. A group of Disclosures where opening one can close the others. Great for FAQs. - [Carousel](https://slab-elements.dev/components/carousel.md): ``, built on `CSS scroll snap +