Primitives Layout and display
Badge
A short label, status or count in a pill, with an optional remove button for tags and chips.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
</script>
<span data-slean="badge">Draft</span>
<span data-slean="badge" data-color="success">Paid</span>
<span data-slean="badge" data-color="error">Overdue</span>Examples
Looks
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
const variants = ['standard', 'filled', 'outlined'];
const colors = ['primary', 'secondary', 'error', 'warning', 'info', 'success', 'neutral'];
</script>
<!-- neutral is the default color, standard (a soft tint) the default variant. -->
{#each variants as variant}
<div class="row">
{#each colors as color}
<span data-slean="badge" data-variant={variant} data-color={color}>{color}</span>
{/each}
</div>
{/each}Sizes
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
</script>
<span data-slean="badge" data-size="small">Small</span>
<span data-slean="badge">Medium</span>
<span data-slean="badge" data-size="large">Large</span>With an icon
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
</script>
<span data-slean="badge" data-color="success">
<svg aria-hidden="true" viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" stroke-width="2">
<path d="M3 8.5l3 3 7-7" />
</svg>
Verified
</span>
<span data-slean="badge" data-color="warning">
<svg aria-hidden="true" viewBox="0 0 16 16" width="12" height="12" fill="currentColor">
<circle cx="8" cy="8" r="4" />
</svg>
Degraded
</span>
<span data-slean="badge" data-variant="outlined">
<svg aria-hidden="true" viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" stroke-width="1.75">
<circle cx="8" cy="8" r="6" />
<path d="M8 4.5V8l2.5 1.5" />
</svg>
Scheduled
</span>Status in a list
- Harbor Studio INV-1042 Paid
- Northwind INV-1043 Due soon
- Kite & Co INV-1044 Overdue
- Aster Labs INV-1045 Draft
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
const invoices = [
{ id: 'INV-1042', client: 'Harbor Studio', status: 'Paid', color: 'success' },
{ id: 'INV-1043', client: 'Northwind', status: 'Due soon', color: 'warning' },
{ id: 'INV-1044', client: 'Kite & Co', status: 'Overdue', color: 'error' },
{ id: 'INV-1045', client: 'Aster Labs', status: 'Draft', color: undefined }
];
</script>
<ul class="invoices">
{#each invoices as invoice (invoice.id)}
<li>
<span>{invoice.client} <small>{invoice.id}</small></span>
<span data-slean="badge" data-color={invoice.color}>{invoice.status}</span>
</li>
{/each}
</ul>
<style>
.invoices {
display: grid;
margin: 0;
padding: 0;
list-style: none;
}
.invoices li {
display: flex;
justify-content: space-between;
align-items: center;
padding-block: 0.625rem;
border-block-end: 1px solid var(--slean-border);
}
</style>Removable
- Design
- Research
- Accessibility
- Archived
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
import { tick } from 'svelte';
let topics = $state([
{ label: 'Design', removable: true },
{ label: 'Research', removable: true },
{ label: 'Accessibility', removable: true, primary: true },
{ label: 'Archived', removable: false }
]);
let list: HTMLUListElement;
// Removal is the application's: drop the item from the data, then move focus to the next
// remove button, or the previous one when none follows.
async function remove(index: number) {
topics.splice(index, 1);
await tick();
const buttons = list.querySelectorAll<HTMLButtonElement>('[data-slean-part="remove"]');
(buttons[index] ?? buttons[index - 1])?.focus();
}
</script>
<ul aria-label="Topics" class="badges" bind:this={list}>
{#each topics as topic, i (topic.label)}
<li>
<span data-slean="badge" data-variant="outlined" data-color={topic.primary ? 'primary' : undefined}
>{topic.label}
{#if topic.removable}
<button type="button" data-slean-part="remove" aria-label="Remove {topic.label}"
onclick={() => remove(i)}></button>
{/if}</span>
</li>
{/each}
</ul>
<style>
.badges {
display: flex;
flex-wrap: wrap;
gap: 0.5rem;
margin: 0;
padding: 0;
list-style: none;
}
</style>Tag input
- svelte
- css
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
import { tick } from 'svelte';
let keywords = $state(['svelte', 'css']);
let draft = $state('');
let input: HTMLInputElement;
let list: HTMLUListElement;
function onkeydown(event: KeyboardEvent) {
const value = draft.trim().toLowerCase();
if (event.key !== 'Enter' || !value) return;
event.preventDefault();
if (!keywords.includes(value)) keywords.push(value);
draft = '';
}
// The next remove button, the previous one, or the input when the list is empty.
async function remove(index: number) {
keywords.splice(index, 1);
await tick();
const buttons = list.querySelectorAll<HTMLButtonElement>('[data-slean-part="remove"]');
(buttons[index] ?? buttons[index - 1] ?? input).focus();
}
</script>
<div data-slean="field">
<label for="keywords" data-slean-part="label">Keywords</label>
<input id="keywords" type="text" data-slean="input" placeholder="Type and press Enter"
bind:value={draft} bind:this={input} {onkeydown} />
</div>
<ul aria-label="Keywords" class="badges" bind:this={list}>
{#each keywords as keyword, i (keyword)}
<li>
<span data-slean="badge" data-variant="outlined">{keyword}
<button type="button" data-slean-part="remove" aria-label="Remove {keyword}"
onclick={() => remove(i)}></button></span>
</li>
{/each}
</ul>Disabled remove button
- Platform
- Billing
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
</script>
<!-- Assigned by an administrator: the remove button is shown, disabled and skipped by Tab. -->
<ul aria-label="Assigned teams" class="badges">
<li>
<span data-slean="badge" data-variant="outlined">Platform
<button type="button" data-slean-part="remove" aria-label="Remove Platform" disabled></button></span>
</li>
<li>
<span data-slean="badge" data-variant="outlined">Billing
<button type="button" data-slean-part="remove" aria-label="Remove Billing" disabled></button></span>
</li>
</ul>Count on an icon button
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/badge.css';
</script>
<!-- The count is part of the button's name; the badge itself is hidden. -->
<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" data-icon-only aria-label="Inbox, 3 unread" class="has-count">
<svg aria-hidden="true" viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linejoin="round">
<path d="M3 13h5l1.5 3h5L16 13h5" />
<path d="M5.5 5h13L21 13v6H3v-6z" />
</svg>
<span data-slean="badge" data-color="error" data-size="small" aria-hidden="true" class="count">3</span>
</button>
<style>
/* The badge package positions nothing: placing it on the corner is the application's CSS. */
.has-count {
position: relative;
}
.count {
position: absolute;
inset-block-start: -0.375rem;
inset-inline-end: -0.375rem;
/* A ring in the page color separates the badge from the button's border. */
box-shadow: 0 0 0 2px var(--slean-bg);
}
</style>Usage
Plain markup with a stylesheet: install @svelte-lean/styles. No JavaScript runs.
npm install @svelte-lean/stylespnpm add @svelte-lean/stylesyarn add @svelte-lean/stylesbun add @svelte-lean/stylesimport '@svelte-lean/styles/badge.css';The color is data-color: primary, secondary, info, success, warning, error or neutral (the default). The fill is data-variant: standard (the default, a soft tint), filled or outlined. Sizes are data-size="small", the default medium and "large".
A badge that changes while the page is open is not announced. When the change matters, write it to a live region (role="status") as well.
A removable badge ends with <button type="button" data-slean-part="remove" aria-label="Remove Design">; put several in a <ul> with a label. On removal, move focus to the next remove button, the previous one when none follows, or the input that adds badges when the list is empty. A badge that toggles a filter is a toggle or a checkbox instead.
Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <span data-slean="badge"> | – | yes | data-color="primary|secondary|info|success|warning|error|neutral" (neutral by default), data-variant="standard|filled|outlined", data-size="small|medium|large". Text inside; several removable badges go in a <ul>. |
| remove | <button type="button" aria-label="Remove …"> | remove | no | The last child, empty; the cross is drawn. The application removes the badge and moves focus. |
Keyboard
| Key | When | Result |
|---|---|---|
| Tab/Shift+Tab | anywhere | Passes the badge by (it is text) and stops on each remove button (native) |
| Enter/Space | focus on a remove button | Activates it; the application removes the badge and moves focus |
Styling
badge.css draws the pill, the standard, filled and outlined variants from the current color, the three sizes, tabular numbers, and the remove button with its masked cross, hover fill, hit area and disabled state. It positions nothing: the count example places the badge with the application's CSS. The tokens it reads:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-space-1 | calc(var(--slean-spacing) * 1) | gap, padding-inline |
--slean-space-2 | calc(var(--slean-spacing) * 2) | padding-inline |
--slean-chip-radius | var(--slean-radius-full) | border-radius |
--slean-color-soft | var(--slean-primary-soft) | background |
--slean-color-soft-text | var(--slean-primary-soft-text) | color |
--slean-text-xs | 0.75rem | font-size |
--slean-font-weight-medium | 500 | font-weight |
--slean-color-main | var(--slean-primary-main) | background |
--slean-color-contrast-text | var(--slean-primary-contrast-text) | color |
--slean-color-border | color-mix(in oklch, var(--slean-primary-main) 50%, transparent) | border-color |
--slean-space-3 | calc(var(--slean-spacing) * 3) | padding-inline |
--slean-text-sm | 0.875rem | font-size |
--slean-radius-sm | calc(var(--slean-radius) * 0.6) | border-radius |
--slean-duration-fast | 100ms | transition |
--slean-ease | cubic-bezier(0.2, 0, 0, 1) | transition |
--slean-icon-close | url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M4.5 4.5l7 7m0-7l-7 7' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E") | mask |
State selectors the stylesheet targets, all from the platform or ARIA: :disabled, :focus-visible, :hover.
Variant attributes: data-variant (filled, outlined); data-size (small, large).
Under the hood
Runtime and size
- Tier
- 0 · Native
- Behavior JS
- 0 B brotli · 0 B gzip ·
fixtures/· methodresults.json (native-only) - Platform features
<span>,text,<button>,aria-label,:has()- Shared listeners
- none
- Per-instance listeners
- none
- Lazy state
- none
- Native base
<span> with an optional remove <button>
Tier 0: no behavior module. The Vite plugin maps badge to no module, and the native-only fixture proves the path ships no Svelte Lean JavaScript.
Why this implementation
A badge is a word or a number in a pill. The browser renders and reads text without help, so the primitive is a stylesheet and a contract: which tokens color each variant, and how a badge takes part in the name of what it labels.
The accessibility questions are the real content. A color is only color, and color alone is not information: forced-colors mode shows every badge alike, so the word has to say it. A count on an icon button is part of the button’s name, not a separate announcement.
A tag is the same label with a remove button, so it is the same primitive with one optional part (ADR 0011 §1.6). The button brings focus, Enter and Space, the click event and a disabled state; removal stays the application’s, because the list is the application’s data. The contract names the step that is easy to miss: after a removal the focused button is gone, and focus falls to the page unless the application moves it.
The browser owns
- the text and its reading order
- the name of the control a count badge sits in (aria-label)
- the remove button: focus, Enter and Space, the click event, disabled, its name from aria-label
- the list semantics of the <ul> that holds removable badges
Svelte Lean owns
- badge.css: the pill, the standard, filled and outlined variants drawn from the current color, three sizes, tabular numbers, the masked cross of the remove button and its 24px hit area
- the contract: the text carries the meaning, the count belongs to the control’s name, where focus goes after a removal
- documentation
Accessibility
- A badge is plain text in the reading order; it has no role and is not focusable.
- The text carries the meaning; the color repeats it, and forced colors show every badge alike with a visible border.
- Inside a control, the count is part of the control’s name (
aria-label="Inbox, 3 unread") and the badge isaria-hidden. - Every standard badge is a soft fill with its own text color from the palette tokens, checked by axe on the playground page.
- The remove part is a native
<button>named byaria-label, reachable with Tab and activated with Enter or Space; its drawn box is small, its hit area is 24 by 24 pixels. A disabled one is skipped by Tab and drawn dimmed,GrayTextin forced colors.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
<span>, text and <button> | Widely available | Not applicable within the support policy |
:has() | Baseline 2023 (Chrome 105, Safari 15.4, Firefox 121) | The padding beside the remove button stays as wide as on the other side |
Without JavaScript
Fully functional; remove buttons do nothing, because removal is application code.
Server rendering and hydration
Static HTML.
The package attaches nothing; hydration attaches the application’s click handlers to remove buttons.
Compatibility
Everything here is widely available. :has() (Baseline 2023) only tightens the padding beside the remove button.
Tests and source
apps/playground/tests/primitives/display.spec.tsPlaywright: open state, exclusive groups, stretched links, roles and names, carousel scrolling, axepackages/styles/testsstatic checks of the stylesheet (layers, tokens, specificity, dark parity)
packages/primitives/src/badge/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/badge/contract.tstyped constants: name, tier, base, parts, options, eventspackages/styles/css/badge.cssthe optional stylesheet