Primitives Layout and display
Keyboard key
The native kbd element drawn as a key, for shortcuts in running text, on buttons and in menus; combinations nest one key per kbd.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Press Ctrl+K to search and Esc to close.
Code
<script lang="ts">
import '@svelte-lean/styles/kbd.css';
</script>
<p>
Press <kbd data-slean="kbd"><kbd>Ctrl</kbd>+<kbd>K</kbd></kbd> to search and
<kbd data-slean="kbd">Esc</kbd> to close.
</p>Examples
Combinations
Ctrl+Shift+P Command palette
Cmd+Enter Send
← → Previous and next tab
Code
<script lang="ts">
import '@svelte-lean/styles/kbd.css';
</script>
<!-- One <kbd> per key inside the root; the plus signs stay text. -->
<p><kbd data-slean="kbd"><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd></kbd> Command palette</p>
<p><kbd data-slean="kbd"><kbd>Cmd</kbd>+<kbd>Enter</kbd></kbd> Send</p>
<p><kbd data-slean="kbd">←</kbd> <kbd data-slean="kbd">→</kbd> Previous and next tab</p>Search shortcut
Code
<script lang="ts">
import '@svelte-lean/styles/input.css';
import '@svelte-lean/styles/kbd.css';
let input = $state<HTMLInputElement>();
// The <kbd> only shows the shortcut; this handler makes it work.
function onkeydown(event: KeyboardEvent) {
if ((event.ctrlKey || event.metaKey) && event.key === 'k') {
event.preventDefault();
input?.focus();
}
}
</script>
<svelte:window {onkeydown} />
<div class="search">
<input
bind:this={input}
type="search"
placeholder="Search the docs"
aria-label="Search the docs"
aria-keyshortcuts="Control+K Meta+K"
data-slean="input"
/>
<kbd data-slean="kbd"><kbd>Ctrl</kbd>+<kbd>K</kbd></kbd>
</div>
<style>
.search {
position: relative;
max-inline-size: 20rem;
}
.search > input {
inline-size: 100%;
padding-inline-end: 5rem;
}
.search > kbd {
position: absolute;
inset-block: 0;
inset-inline-end: 0.5rem;
margin-block: auto;
pointer-events: none;
}
</style>In a menu
Code
<script lang="ts">
// role="menu" is Tier 1: @svelte-lean/vite registers the menu behavior.
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/kbd.css';
import '@svelte-lean/styles/menu.css';
</script>
<button
type="button"
id="kbd-edit-button"
popovertarget="kbd-edit-menu"
aria-haspopup="menu"
data-slean="button"
data-variant="outlined"
data-color="neutral"
>
Edit
</button>
<div id="kbd-edit-menu" popover role="menu" aria-labelledby="kbd-edit-button" data-slean="menu">
<button type="button" role="menuitem" aria-keyshortcuts="Control+Z">
Undo <kbd data-slean="kbd"><kbd>Ctrl</kbd>+<kbd>Z</kbd></kbd>
</button>
<button type="button" role="menuitem" aria-keyshortcuts="Control+Shift+Z">
Redo
<kbd data-slean="kbd"><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd></kbd>
</button>
<hr />
<button type="button" role="menuitem" aria-keyshortcuts="Control+C">
Copy <kbd data-slean="kbd"><kbd>Ctrl</kbd>+<kbd>C</kbd></kbd>
</button>
<button type="button" role="menuitem" aria-keyshortcuts="Control+V">
Paste <kbd data-slean="kbd"><kbd>Ctrl</kbd>+<kbd>V</kbd></kbd>
</button>
</div>Shortcut list
- Save
- Ctrl+S
- Find in the page
- Ctrl+F
- New window
- Ctrl+Shift+N
- Switch application
- Alt+Tab
Code
<script lang="ts">
import '@svelte-lean/styles/kbd.css';
const shortcuts = [
{ keys: ['Ctrl', 'S'], action: 'Save' },
{ keys: ['Ctrl', 'F'], action: 'Find in the page' },
{ keys: ['Ctrl', 'Shift', 'N'], action: 'New window' },
{ keys: ['Alt', 'Tab'], action: 'Switch application' }
];
</script>
<dl class="shortcuts">
{#each shortcuts as shortcut (shortcut.action)}
<dt>{shortcut.action}</dt>
<dd>
<kbd data-slean="kbd">
{#each shortcut.keys as key, i (key)}{#if i > 0}+{/if}<kbd>{key}</kbd>{/each}
</kbd>
</dd>
{/each}
</dl>
<style>
.shortcuts {
display: grid;
grid-template-columns: 1fr auto;
gap: 0.75rem 2rem;
max-inline-size: 24rem;
margin: 0;
}
.shortcuts dd {
margin: 0;
}
</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/kbd.css';Write key names as text: Ctrl, Shift, Enter. Symbols such as ⌘ and ⇧ are read differently, or not at all, by screen readers; when you show one, add the name as visually hidden text.
For a combination, put one <kbd> per key inside the root and keep the plus signs as text between them.
Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <kbd data-slean="kbd"> | – | yes | One key as text, or one <kbd> per key for a combination. |
| key | <kbd> inside the root | – | no | Drawn as keys; the root around them draws nothing. |
Keyboard
| Key | When | Result |
|---|---|---|
| Tab | anywhere | Passes the key by: it is text, not a control |
Styling
kbd.css draws a key as a bordered box with a thicker bottom edge in the page font, and, through :has(), draws the inner keys of a combination instead of the root. The tokens it reads:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-border-strong | var(--slean-neutral-8) | border |
--slean-radius-sm | calc(var(--slean-radius) * 0.6) | border-radius |
--slean-surface | oklch(100% 0 0) | background |
--slean-fg | var(--slean-neutral-12) | color |
--slean-text-xs | 0.75rem | font-size |
--slean-font-weight-medium | 500 | font-weight |
--slean-fg-muted | var(--slean-neutral-11) | color |
Under the hood
Runtime and size
- Tier
- 0 · Native
- Behavior JS
- 0 B brotli · 0 B gzip ·
fixtures/· methodresults.json (native-only) - Platform features
<kbd>,nested <kbd>,:has()- Shared listeners
- none
- Per-instance listeners
- none
- Lazy state
- none
- Native base
<kbd>
Tier 0: the key has no behavior module, the Vite plugin maps kbd to no module, and the native-only fixture proves the path ships no Svelte Lean JavaScript.
Why this implementation
<kbd> is HTML for user input, and nesting it is HTML for a combination: the outer element is the whole input, the inner ones are the keys. Browsers and screen readers read it as text. The primitive is the drawing of a key and the rule that a combination is drawn key by key.
Where a shortcut exists, it belongs to a control. aria-keyshortcuts on that control announces it; the <kbd> only shows it.
The browser owns
- the <kbd> element as user input, and the nested form of a key combination
- the text screen readers read out
Svelte Lean owns
- kbd.css: the key box with a thicker bottom edge, the combination drawn key by key
- the contract: key names as text, aria-keyshortcuts on the control
- documentation
Accessibility
<kbd>is text; screen readers read the key names in order, the plus signs included.- The shortcut itself is announced from
aria-keyshortcutson the control it activates, not from the<kbd>. - Keys are not focusable and have no role.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
<kbd> | Widely available | Not applicable within the support policy |
:has() | Baseline 2023, widely available since June 2026 | A combination is drawn as one box around its keys |
Without JavaScript
Fully functional.
Server rendering and hydration
Static HTML.
Nothing is attached.
Compatibility
<kbd> is widely available. :has() is Baseline 2023 and widely available since June 2026; without it a combination is drawn as one box around its keys.
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/kbd/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/kbd/contract.tstyped constants: name, tier, base, parts, options, eventspackages/styles/css/kbd.cssthe optional stylesheet