component styling #

A component's styling hooks are the CSS custom properties a consumer can set to style it. Each component lists them in cssCustomProperties, as ComponentCssPropertyJson entries. Two kinds are found in its styles automatically: a var() read with a fallback, and a property registered with an @property rule. You can also document any property with a @cssprop tag in the doc comment.

Example
#

<!-- @component A card. @cssprop {<length>} [--card_width=20rem] - the card's width @cssprop --card_padding - the inner padding --> <div class="card"></div> <style> @property --card_padding { syntax: '<length>'; inherits: true; initial-value: 1rem; } .card { width: var(--card_width, 20rem); padding: var(--card_padding); background: var(--card_bg, white); border-radius: var(--border_radius, 4px); color: var(--text_color); } </style>

The component's cssCustomProperties:

[ { "name": "--card_width", "description": "the card's width", "syntax": "<length>", "fallback": "20rem", "default": "20rem", "sourceLine": 17, "documented": true }, { "name": "--card_padding", "description": "the inner padding", "syntax": "<length>", "fallback": "1rem", "sourceLine": 18, "documented": true }, {"name": "--card_bg", "fallback": "white", "sourceLine": 19}, {"name": "--border_radius", "fallback": "4px", "sourceLine": 20} ]
  • --card_width is read with a fallback and tagged: the tag gives description, syntax, and default; the read gives fallback and sourceLine.
  • --card_padding is read bare, which alone wouldn't list it, but its @property rule registers it: the rule supplies syntax, and its initial-value becomes fallback.
  • --card_bg is a plain fallback read, listed without a tag.
  • --border_radius is a global design token, but it's read with a fallback, so it's listed too; see choosing what to show.
  • --text_color is read bare and registered nowhere, so it isn't listed: bare reads are mostly global tokens the component consumes, not hooks it offers.

Documented entries come first, in tag order, then the rest in the order of each name's first read. The output format describes each field.

Fallback reads
#

Svelte's docs use var(--track-color, #aaa) to expose a styling hook, so any var() with a fallback counts as one. Reads are found in:

  • the component's top-level <style>, at any depth: nested rules, @media/@container/@supports blocks, keyframes, :global
  • the static text of the markup's style attributes and style: directives on elements
  • the static text of a child component's style and --a attributes (<Child --a="var(--b, 1px)" /> reads --b)

Only the outermost var() counts: var(--a, var(--b)) lists --a, with --b part of its fallback. A name the component sets itself isn't listed, since its own value shadows a consumer's: a --a: … declaration in its style, a style:--a directive, or --a: in an element's style attribute. A --a or style attribute on a child component styles the child, not this one. Names are case-sensitive, as in CSS.

fallback is the verbatim source text after the comma, trimmed, comments and line breaks included; it's empty for var(--a,). When a name is read several times, sourceLine comes from the first read and fallback from the first read that has one, so a bare read before a fallback read doesn't keep the name off the list.

@property
#

An @property rule in the component's style registers a custom property with the browser, so the property is listed even when every read is bare. The rule's syntax descriptor becomes syntax, quotes stripped, and its initial-value becomes fallback: a registered property is never unset, so the initial value wins over any var() fallback. When several rules name one property, the last wins, as in CSS. A registered name nothing reads isn't listed.

inherits isn't modeled. With inherits: false, a consumer's value never reaches the component's elements, so the property isn't a hook at all; register hooks with inherits: true. Svelte doesn't scope @property rules, so a registration applies to the whole page.

@cssprop
#

@cssprop in the component's doc comment documents a property, in the Custom Elements Manifest form (@cssproperty is a synonym):

@cssprop {<syntax>} [--name=default] - description
PartField
{<syntax>}syntax, verbatim and unvalidated (<color>, <length> | auto). Optional; without it, an @property rule's syntax fills in.
--namename, -- included. The brackets are optional without a default.
=defaultdefault, verbatim and trimmed; nested brackets and quoted strings are fine ([--a=var(--b, 1px)]). Optional.
- descriptiondescription, raw like docComment, continuation lines included. The dash is optional. Inline {@link} is kept for the renderer.

A tagged property is always listed, with documented: true. Use a tag to describe a hook, or to list one the fallback rule misses, like a bare read (width: var(--card_width)). A tagged name the component reads anywhere (bare, nested in another fallback, in the markup's static style text, even one it sets itself) merges with the read, taking its sourceLine and fallback. A tagged name it never reads takes the tag's line and warns unknown_cssprop.

default is the author's claim and fallback the style's fact, kept side by side so neither hides the other; a renderer wanting one value takes default ?? fallback. When both exist and differ (compared as text, whitespace runs collapsed), cssprop_default_mismatch warns; usually the style changed and the tag didn't. Nothing evaluates CSS, so red against #f00 warns too: write the default as the style does, or omit it and let fallback speak.

Tags come from the one comment that documents the component: the JSDoc above $props() when it has prose or a tag (a bare @type doesn't count), else the HTML @component comment. When both have content, even a JSDoc of tags alone, duplicate_comment warns and the HTML comment is ignored, prose and tags alike, so keep the tags beside the component's prose. Legacy export let components read only the HTML comment. A tag on a prop, a member, or anything but a component documents no property (see tags).

Warnings
#

Each warning carries the component's name and a line. None removes a listed property; only a malformed or repeated tag is itself dropped. The full list is in diagnostics.

kindWhen
unknown_csspropa tag names a property the component never reads: a typo, a stale tag, or one it leaves to a child (reads aren't resolved across components)
cssprop_default_mismatcha tag's default differs from the style's fallback
malformed_taga tag names no -- property (@cssprop card_width, an unclosed brace or bracket, an empty tag); it's dropped
duplicate_taga tag repeats a name an earlier tag documents; the first wins
css_lang_unsupported, css_parse_failedthe style wasn't read (below); the tags are listed unchecked, with no fallback

Choosing what to show
#

A global design token read with a fallback, like var(--border_radius, 4px) in the example, lists as a hook too, because the analyzer can't tell a token from a hook. In your own components, drop the fallback when the token always exists, or tag the real hooks so consumers can show only those.

There's deliberately no option to filter during analysis: the output keeps every read, and a consumer that wants fewer filters them. A common rule: show the documented entries when a component has any, else all of them:

const documented = declaration.cssCustomProperties.filter((p) => p.documented); const shown = documented.length > 0 ? documented : declaration.cssCustomProperties;

An entry maps onto a Custom Elements Manifest cssProperties entry field for field (name, description, syntax, default); fallback, sourceLine, and documented have no manifest counterpart.

What isn't read
#

  • a <style lang="scss">, or any language but CSS (warns css_lang_unsupported)
  • a component Svelte's parser rejects: malformed CSS, or markup its loose parsing can't absorb (warns css_parse_failed)
  • reads inside a dynamic style expression (style="color: {c}"), or in a <svelte:head> style
  • properties set from script (style.setProperty) or in a dynamic style expression: they count as unset, so their fallback reads stay listed
  • reads in another component: a wrapper documenting a property its child reads through inheritance warns unknown_cssprop