Tag

Example

<ul aria-label="Topics" class="tags">
	<li>
		<span data-slean="tag">Design
			<button type="button" data-slean-part="remove" aria-label="Remove Design"></button></span>
	</li>
	<li>
		<span data-slean="tag">Research
			<button type="button" data-slean-part="remove" aria-label="Remove Research"></button></span>
	</li>
	<li>
		<span data-slean="tag" data-variant="accent">Accessibility
			<button type="button" data-slean-part="remove" aria-label="Remove Accessibility"></button></span>
	</li>
	<li><span data-slean="tag">Archived</span></li>
</ul>

<script lang="ts">
	import '@svelte-lean/styles/tag.css';
	import { tick } from 'svelte';

	let tags = $state([
		{ label: 'Design', removable: true },
		{ label: 'Research', removable: true },
		{ label: 'Accessibility', removable: true, accent: true },
		{ label: 'Archived', removable: false }
	]);
	let list: HTMLUListElement;

	// Removal is the application's: drop the tag from the data, then move focus to the next
	// remove button, or the previous one when none follows.
	async function remove(index: number) {
		tags.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="tags" bind:this={list}>
	{#each tags as tag, i (tag.label)}
		<li>
			<span data-slean="tag" data-variant={tag.accent ? 'accent' : undefined}>{tag.label}
				{#if tag.removable}
					<button type="button" data-slean-part="remove" aria-label="Remove {tag.label}"
						onclick={() => remove(i)}></button>
				{/if}</span>
		</li>
	{/each}
</ul>

<style>
	.tags {
		display: flex;
		flex-wrap: wrap;
		gap: 0.5rem;
		margin: 0;
		padding: 0;
		list-style: none;
	}
</style>

Why this implementation exists

A tag is text in a box, and its remove control is a button. The button brings focus, Enter and Space, the click event and a disabled state with it; the tag needs no behavior of its own.

Removal is where component libraries hold state: a list of values, an onRemove callback, a focus move. The list is already the application’s data, so the application removes the item and Svelte removes the element. The contract names the one 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.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/tag.css';

Name every remove button after its tag (aria-label="Remove Design"); the cross is drawn and the button has no text. Put a set of tags in a <ul> with a label.

On removal, move focus to the next remove button, the previous one when none follows, or to the input that adds tags when the list is empty. A tag that toggles a filter is a Toggle or a checkbox instead.

Anatomy

Runtime profile

Tier 0: the tag has no behavior module, the Vite plugin maps tag to no module, and the native-only fixture proves the path ships no Svelte Lean JavaScript. The click handler in the example is the page's own code.

Accessibility contract

• The remove part is a native <button> named by aria-label, reachable with Tab and activated with Enter or Space.
• The cross is drawn on ::before and ::after with borders; forced colors keep it because it is currentColor.
• After a removal focus goes where the application sends it; without that step it falls to the document body.
• A disabled remove button is skipped by Tab and drawn at reduced opacity, GrayText in forced colors.

Keyboard

Platform features

Without JavaScript

The tags render; the remove buttons do nothing, because removal is application code.

Server rendering

Static HTML.

Before hydration

Before hydration the remove buttons do nothing. Hydration attaches the application's click handler; the package attaches nothing.

Styling

tag.css draws the label box, the accent variant, the remove button and its cross, its hover fill, a larger target on coarse pointers, and the disabled state. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :disabled, :focus-visible, :hover.

Variant attributes: data-variant (accent).

Compatibility notes

Everything here is widely available. :has() (Baseline 2023) only tightens the padding beside the remove button.

Testing

• apps/playground/tests/primitives/display.spec.ts Playwright: open state, exclusive groups, stretched links, roles and names, carousel scrolling, axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/tag/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/tag/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/tag.css the optional stylesheet