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_widthis read with a fallback and tagged: the tag givesdescription,syntax, anddefault; the read givesfallbackandsourceLine.--card_paddingis read bare, which alone wouldn't list it, but its@propertyrule registers it: the rule suppliessyntax, and itsinitial-valuebecomesfallback.--card_bgis a plain fallback read, listed without a tag.--border_radiusis a global design token, but it's read with a fallback, so it's listed too; see choosing what to show.--text_coloris 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/@supportsblocks, keyframes,:global - the static text of the markup's
styleattributes andstyle:directives on elements - the static text of a child component's
styleand--aattributes (<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 | Part | Field |
|---|---|
{<syntax>} | syntax, verbatim and unvalidated (<color>, <length> | auto). Optional; without it, an @property rule's syntax fills in. |
--name | name, -- included. The brackets are optional without a
default. |
=default | default, verbatim and trimmed; nested brackets and quoted strings are fine
([--a=var(--b, 1px)]). Optional. |
- description | description, 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.
| kind | When |
|---|---|
unknown_cssprop | a 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_mismatch | a tag's default differs from the style's fallback |
malformed_tag | a tag names no -- property (@cssprop card_width, an unclosed
brace or bracket, an empty tag); it's dropped |
duplicate_tag | a tag repeats a name an earlier tag documents; the first wins |
css_lang_unsupported, css_parse_failed | the 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 (warnscss_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
styleexpression (style="color: {c}"), or in a<svelte:head>style - properties set from script (
style.setProperty) or in a dynamicstyleexpression: 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