svelterm feature reference

svelterm renders Svelte components to a terminal cell grid with HTML/CSS semantics. This is the authoritative list of what is supported, what is approximated, and what is deliberately ignored. Standard features link to MDN rather than re-explaining them; terminal-specific behaviour is documented in full here.

The rule: any feature with a sensible meaning on a grid of character cells works the way a browser author expects. Features with no cell-grid meaning (pixels, fonts, sub-cell geometry) parse and are silently dropped — never a crash. Target modes separately with @media (display-mode: terminal) / @media (display-mode: browser).

Terminal-specific extensions

These do not exist in browsers and are svelterm’s own surface.

The cell unit

One terminal cell — the atomic unit of layout. width: 20cell, padding: 1cell 2cell. ch is accepted as an exact alias (1ch = 1cell), which lets stylesheets work in both modes. All lengths round to whole cells. Unitless 0 is valid.

@media (display-mode: terminal | browser)

Reuses the standard display-mode media feature with two custom values. The terminal renderer evaluates terminal as true; real browsers never match either custom value, but a browser block simply applies as normal CSS there. This is the documented pattern for anything in the ignored bucket:

.card {
    @media (display-mode: browser)  { box-shadow: 0 2px 8px #0004; }
    @media (display-mode: terminal) { border: single; }
}

Border styles

border-style takes terminal-native values drawn with box-drawing and block glyphs (browser values like solid/dashed are ignored — use a display-mode block):

Borders are 1 cell thick. border-top/right/bottom/left: true|false enable individual sides. border-corner: h | v | none picks corner character bias. border-color works as standard (including currentColor).

Colour on a terminal

Resolved colours are either ANSI palette names (red, cyan, …) or 24-bit truecolor. CSS keywords that match the 8 basic ANSI names map to palette entries (themeable by the user’s terminal); explicit hex/rgb() etc. stay exact. transparent means “no colour set” — the parent’s background shows through. The terminal’s own dark/light scheme is detected via OSC 11 polling (overridable through run({ colorScheme })) and drives light-dark() and @media (prefers-color-scheme: …).

opacity ≈ dim

There is no alpha channel. opacity below 1 applies the terminal’s dim attribute; the non-standard value opacity: dim does the same explicitly.

<svt-region>

A paint primitive that fills its layout box from a consumer-provided cell source (used to embed full terminal emulators). It fires a resize event with { cols, rows } when its allocated size changes. Without an explicit size it fills the parent box like a replaced element.

Focus and keys

Tab/Shift+Tab cycle focusable elements (button, input, textarea, a, select, summary); disabled controls are skipped. The focused element matches :focus. Enter clicks the focused element (opens href on links, toggles <details>, cycles <select>); Space toggles checkboxes/radios and cycles selects. Mouse clicks focus, click, and activate the same defaults. Clicking a <label> activates its control — wrapping or for="id" association both work. Ctrl+C exits.

Text editing

Focused input/textarea fields have readline-style editing (the same keymap as sumi’s editable elements):

Kills feed a kill ring; cut/copy also write the system clipboard (OSC 52 plus the platform tool). Typing, Enter, or paste replaces an active selection; Backspace/Delete remove it. Clicking an input places the caret; double-click selects the clicked word and copies it, like the screen-space selection. Words are whitespace-delimited.

In a textarea the same keymap gains lines: Enter inserts a newline, ↑/↓ move by line (column clamped to the target line, as in sumi), Shift+↑/↓ extends the selection, the view scrolls to follow the caret, and the selection highlight paints across rows. input fires on value changes; caret-only movement fires selectionchange with { value, cursor } for status bars.

Interaction model for form controls

• Checkbox renders [x] / [ ]; radio renders (•) / ( ) (3×1 cells). Radios group by name across the tree.
• <select> is a popup-less cycling control: it renders the selected option’s label plus ▾, sized to the longest option. ArrowUp/ ArrowDown move the selection (wrapping); Space/Enter/click advance. There is no dropdown popup — it has no good cell-grid answer.
• <progress>/<meter> render as 20×1 block-glyph bars (█ fill with eighth-block partials, ░ track), stylable via color/ background, sized via width/height.

Events

W3C-style capture/bubble dispatch on the component tree: click, keydown, input, change, paste, toggle (details), resize (svt-region), plus mouse events with cell coordinates. Event payloads ride on event.data (e.g. { value, cursor }, { checked }).

HTML elements

Standard semantics unless noted. Anything unlisted renders as a plain block/inline box per its display default.

CSS selectors

All standard matching semantics. Reference: MDN selectors.

• Type, .class, #id, *, selector lists (a, b)
• Combinators: descendant, >, +, ~
• Attributes: [a], [a=v], [a^=v], [a$=v], [a*=v], [a~=v], [a|=v] (quoted or unquoted values)
• Pseudo-classes: :root, :focus, :hover (mouse), :first-child, :last-child, :only-child, :empty, :first-of-type, :last-of-type, :only-of-type, :nth-child(), :nth-last-child(), :nth-of-type(), :nth-last-of-type() (full An+B), :not(), :is(), :where(), :checked, :disabled, :enabled
• Pseudo-elements: ::before, ::after (single-colon legacy accepted) with content: strings, attr(x), counter(name) (with counter-reset / counter-increment, including explicit amounts), space-separated concatenation, and none/"". Counters use a flat namespace — no per-scope nesting or counters() joining — and update on full style resolution, so an incremental restyle can serve stale numbers until the next full pass. Pseudo boxes are inline and invisible to :empty/:nth-*. In table-internal boxes they render per §17.2.1: a pseudo on a row or table box becomes an anonymous cell/row.
• Specificity, source order, and inline-style precedence follow the cascade.

CSS properties

Grouped; all standard behaviour (per MDN) except the noted grid adaptations. Lengths are cells (cell/ch, %, or calc()).

Animation & transition semantics on the grid

Colours interpolate in RGB at ~30fps; single cell/ch lengths interpolate to whole cells (movement steps cell by cell); every other supported property applies discretely, switching at the segment midpoint (the CSS rule for non-interpolable values). Layout-affecting animations re-flow each frame. Easing applies per keyframe segment (a timing function declared inside a keyframe overrides the element’s for that segment); non-interpolable values switch when eased progress crosses the midpoint. Transitions run per property with their own duration/timing; interruptions continue from the current blended value. Keyframe var()/light-dark() re-resolves on scheme/custom-property changes without restarting the animation. Deviation: no transition-delay / animation-delay.

Values, functions and at-rules

• Units: cell/ch, %, unitless 0, fr (grid). Everything pixel-derived is dropped (see below).
• var() custom properties with inheritance and fallbacks.
• calc(), min(), max(), clamp() over cells and %.
• Colours: hex (3/6/8 digit), rgb()/rgba(), hsl()/hsla(), hwb(), lab(), lch(), oklab(), oklch() (legacy and modern syntax), all 148 named colours, transparent, currentColor, light-dark(). Alpha composites at paint time (blends over the cell beneath), and numeric opacity acts as a blend factor.
• Keywords: inherit, initial, unset.
• At-rules: @media (prefers-color-scheme, display-mode, min/max-width, min/max-height — in cells), @container (size queries against the nearest laid-out ancestor), @supports (property-name checks), @keyframes. Nested rules inside declarations (& {}-less media nesting) are supported.

Ignored (no cell-grid meaning)

These parse and are dropped silently. Use @media (display-mode: browser) for the browser-side styling and a terminal-native equivalent if needed.

px/em/rem/ex/vw/vh lengths · font-size, font-family, line-height, letter-spacing, word-spacing · border-radius (use border: rounded), box-shadow, outline, filter, backdrop-filter · transform and friends · background-image, gradients · float · @font-face, @page.