Components
A component is one .html file: an optional <script> for state and behavior, one root element, an optional <style> scoped to it. The build expands it in place, so the markup arrives prebuilt and the script loads only on pages that use it.
One file: script, markup and style
A top-level let is state, export let is a prop, a function is an action or a derived value, and {$count} puts a value in the text.
routes/examples/components/_components/counter/counter.html
<script> export let label = '' export let start = 0 export let step = 1 let count = start const atMinimum = () => count - step < 0 const atStart = () => count === start function stepSize(event) { return event.shiftKey ? step * 10 : step } function decrease(event) { count = Math.max(0, count - stepSize(event)) } function increase(event) { count += stepSize(event) } function reset(el) { count = start el.parentElement.querySelector('[aria-label="Increase"]').focus() }</script><div role="group" aria-label="{$label}"> <span class="counter-label">{$label}</span> <div class="counter-controls"> <button type="button" class="counter-step" aria-label="Decrease" @click="decrease" :disabled="$atMinimum">−</button> <output class="counter-value">{$count}</output> <button type="button" class="counter-step" aria-label="Increase" @click="increase">+</button> </div> <button type="button" class="counter-reset" @click="reset(el)" :disabled="$atStart">Reset</button></div><style> [data-c="counter"] { display: grid; justify-items: center; gap: 1rem; } .counter-label { color: var(--color-muted); font-family: var(--font-mono); font-size: 0.75rem; } .counter-controls { display: flex; border: 1px solid var(--color-line-strong); background: var(--color-surface); } .counter-step { width: 3rem; font-size: 1.25rem; cursor: pointer; } .counter-step:hover { background: var(--color-raised); } .counter-step:disabled { color: var(--color-faint); cursor: not-allowed; } .counter-value { min-width: 5rem; padding: 0.75rem 1rem; border-inline: 1px solid var(--color-line-strong); font-family: var(--font-mono); font-size: 1.75rem; font-variant-numeric: tabular-nums; text-align: center; } .counter-reset { color: var(--color-muted); font-family: var(--font-mono); font-size: 0.75rem; text-decoration: underline; text-underline-offset: 0.3em; cursor: pointer; } .counter-reset:disabled { visibility: hidden; }</style>
routes/examples/components/_snippets/counter/usage.html
<p-counter label="Steps of 5" start="10" step="5"></p-counter>
Live result
export let start = 0declares a prop with a default. The default's type converts the attribute:start="10"arrives as the number10, so noNumber()anywhere. Props are read-only:let count = startcopies one into state.const atMinimum = () => …is a derived value: used in a binding (:disabled="$atMinimum"), it runs on every render. In JS you call it:atMinimum().function increase(event)is an action when an event names it. Without parentheses,@click="increase"passes the DOM event, here to readevent.shiftKey. Assigningcountschedules one render per microtask; there is nosetStateand nothis.- With parentheses the function gets only what you list: paths, literals,
eventandel, the element that has the@. Reset hides itself after a click, so@click="reset(el)"moves the focus to + and keyboard users keep their place. - A store function works the same way, with no wrapper:
@click="shared.cart.add(product)". A component that only reads and calls a store needs no script, as on the stores page. <style>is scoped by the build:.counter-steponly matches inside this component, with no added specificity, so write plain selectors.:global(…)opts out only what is inside it (:global(html[data-theme="dark"]) .counter-stepis still this component's buttons), and the root itself is[data-c="counter"]. A separatecounter.cssworks the same way; having both it and the<style>(or a<script>and acounter.js) is a check error (html/duplicate-module).
The component lives in _components/counter/ next to this page, so it is used as <p-counter>. Moving the folder to lib/components/ would make it <c-counter> for every route.
Slots: content that belongs to the caller
A component places the caller's children with <slot>; those children keep their own owner.
routes/examples/components/_snippets/slots/usage.html
<p-panel heading="Release notes"> <p>npm packages are bundled with rolldown and tree-shaken per route.</p> <button slot="actions" type="button" class="btn btn-small" @click="like">Like</button> <span slot="actions">{$likesText}</span></p-panel><p-panel heading="Empty panel"></p-panel>
routes/examples/components/index.js
import { data } from 'pragma'let likes = 0let query = ''const likesText = () => (likes === 1 ? '1 like' : likes + ' likes')function visiblePlugins() { const needle = query.trim().toLowerCase() return (data?.plugins ?? []).filter(plugin => plugin.name.includes(needle) || plugin.kind.includes(needle))}function like() { likes += 1}
routes/examples/components/_components/panel/panel.html
<script> export let heading = '' let collapsed = false const expanded = () => String(!collapsed) const toggleText = () => (collapsed ? 'Show' : 'Hide') function toggle() { collapsed = !collapsed }</script><section aria-label="{$heading}"> <header class="panel-head"> <h3 class="panel-heading">{$heading}</h3> <button type="button" class="panel-toggle" @click="toggle" :aria-expanded="$expanded">{$toggleText}</button> </header> <div class="panel-body" :hidden="$collapsed"> <slot><p class="panel-empty">Nothing here yet.</p></slot> </div> <footer class="panel-actions"><slot name="actions"></slot></footer></section><style> [data-c="panel"] { width: 100%; max-width: 22rem; border: 1px solid var(--color-line-strong); background: var(--color-surface); } .panel-head { display: flex; align-items: center; justify-content: space-between; gap: 1rem; padding: 0.625rem 0.75rem 0.625rem 1rem; border-bottom: 1px solid var(--color-line); } .panel-heading { font-size: 0.8125rem; font-weight: 500; } .panel-toggle { min-width: 3rem; padding: 0.25rem 0.5rem; color: var(--color-muted); font-family: var(--font-mono); font-size: 0.75rem; cursor: pointer; } .panel-toggle:hover { color: var(--color-ink); } .panel-body { padding: 1rem; color: var(--color-muted); font-size: 0.9375rem; line-height: 1.6; } .panel-empty { color: var(--color-faint); font-style: italic; } .panel-actions { display: flex; align-items: center; gap: 0.75rem; padding: 0 1rem 1rem; color: var(--color-muted); font-family: var(--font-mono); font-size: 0.75rem; } .panel-actions:empty { display: none; }</style>
Live result
Release notes
npm packages are bundled with rolldown and tree-shaken per route.
Empty panel
Nothing here yet.
<slot> receives the children and <slot name="actions"> receives the children marked slot="actions". Children of a <slot> are fallback content, rendered only when the caller passes nothing: the second panel shows it.
The Like button sits inside <p-panel>, yet @click="like" and {$likesText} resolve in the page script (index.js), while Hide calls the panel's own toggle, with separate state per instance.
Dynamic props from a list
:plugin="plugin" passes a value that updates on every render.
routes/examples/components/_snippets/dynamic-props/usage.html
<p-search-field label="Filter packages" placeholder="Filter by name or kind" :value="$query"></p-search-field><ul> <for plugin in $visiblePlugins key=plugin.id> <p-plugin-row :plugin="plugin"></p-plugin-row> </for> <empty> <li>No package matches.</li> </empty></ul>
routes/examples/components/index.js
import { data } from 'pragma'let likes = 0let query = ''const likesText = () => (likes === 1 ? '1 like' : likes + ' likes')function visiblePlugins() { const needle = query.trim().toLowerCase() return (data?.plugins ?? []).filter(plugin => plugin.name.includes(needle) || plugin.kind.includes(needle))}function like() { likes += 1}
routes/examples/components/_plugins.server.js
export const plugins = [ { id: 'dayjs', name: 'dayjs', kind: 'cjs', size: '3.7 kB' }, { id: 'chart', name: 'chart.js', kind: 'esm', size: '46.0 kB' }, { id: 'toolkit', name: 'es-toolkit', kind: 'esm', size: '0.4 kB' }, { id: 'highlight', name: 'highlight.js', kind: 'cjs', size: '14.8 kB' }, { id: 'fuse', name: 'fuse.js', kind: 'esm', size: '9.2 kB' },]
routes/examples/components/_components/search-field/search-field.html
<input type="search" autocomplete="off" placeholder="{$placeholder}" aria-label="{$label}" :model="$value"><style> [data-c="search-field"] { width: 100%; height: 2.5rem; padding: 0 0.75rem; border: 1px solid var(--color-line-strong); background: var(--color-sunken); color: var(--color-ink); font-family: var(--font-mono); font-size: 0.8125rem; } [data-c="search-field"]::placeholder { color: var(--color-faint); } [data-c="search-field"]:focus-visible { outline-offset: 0; border-color: var(--color-accent); }</style>
routes/examples/components/_components/plugin-row/plugin-row.html
<li> <span class="plugin-name">{$plugin.name}</span> <span class="plugin-kind">{$plugin.kind}</span> <span class="plugin-size">{$plugin.size}</span></li><style> [data-c="plugin-row"] { display: grid; grid-template-columns: 1fr auto 4.5rem; gap: 1rem; padding: 0.625rem 0.75rem; border-bottom: 1px solid var(--color-line); font-family: var(--font-mono); font-size: 0.75rem; } .plugin-name { color: var(--color-ink); } .plugin-kind { color: var(--color-faint); } .plugin-size { color: var(--color-muted); font-variant-numeric: tabular-nums; text-align: right; }</style>
Live result
- dayjs cjs 3.7 kB
- chart.js esm 46.0 kB
- es-toolkit esm 0.4 kB
- highlight.js cjs 14.8 kB
- fuse.js esm 9.2 kB
- No package matches.
Neither component has a script. In a component without a script, {$plugin.name} is an alias to the caller's path, resolved at build time, and :model="$value" writes straight back into the page's query, so the search field needs no code at all.
In a component with a script, export let plugin = null receives the object itself, live on every render, in HTML ($plugin.name) and in JS (plugin.name). It is read-only inside too: it is the caller's data, and in dev plugin.name = 'x' throws "props are read-only, also inside". Copy what you change (let rows = files.map(file => ({ ...file }))) or ask the owner to change it. The page script reads the loader's result with import { data } from 'pragma'.
No script: build-time props, class and slot fallback
A component without a script is fully expanded at build and ships zero JavaScript.
routes/examples/components/_snippets/badge/usage.html
<p-badge label="New" active icon class="m-1"></p-badge><p-badge label="Beta" active="false" class="m-1">caller text</p-badge>
routes/examples/components/_components/badge/badge.html
<span .badge-active="$active" title="{$label}"> <if $icon> <svg class="badge-icon" viewBox="0 0 8 8" aria-hidden="true"><circle cx="4" cy="4" r="3"></circle></svg> </if> <span>{$label}</span> <span class="badge-note"><slot>default text</slot></span></span><style> [data-c="badge"] { display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.25rem 0.625rem; border: 1px solid var(--color-line-strong); color: var(--color-muted); font-family: var(--font-mono); font-size: 0.75rem; } [data-c="badge"].badge-active { border-color: var(--color-accent); color: var(--color-accent); } .badge-icon { width: 0.5rem; height: 0.5rem; fill: currentColor; } .badge-note { color: var(--color-faint); }</style>
Live result
Without a script, {$label} is replaced by the caller's text at build time. A bare attribute like active is truthy; a missing one, "" and "false" are falsy. class on the tag is appended to the root's classes.
Typed props: the default decides the type
An attribute is always text; export let converts it with the type of its default.
routes/examples/components/_components/prop-probe/prop-probe.html
<script> export let call = '' export let step = 1 export let locked = false export let label = 'none' const describe = value => JSON.stringify(value) + ' · ' + typeof value const stepValue = () => describe(step) const lockedValue = () => describe(locked) const labelValue = () => describe(label)</script><dl> <dt class="probe-call">{$call}</dt> <dd class="probe-row"><code>step = 1</code><strong>{$stepValue}</strong></dd> <dd class="probe-row"><code>locked = false</code><strong .probe-yes="$locked">{$lockedValue}</strong></dd> <dd class="probe-row"><code>label = 'none'</code><strong>{$labelValue}</strong></dd></dl><style> [data-c="prop-probe"] { display: grid; gap: 0.375rem; width: 100%; max-width: 22rem; padding: 0.875rem 1rem; border: 1px solid var(--color-line); background: var(--color-surface); font-family: var(--font-mono); font-size: 0.75rem; } .probe-call { margin-bottom: 0.25rem; color: var(--color-ink); } .probe-row { display: flex; justify-content: space-between; gap: 1rem; color: var(--color-muted); } code { color: var(--color-faint); } strong { font-weight: 500; } .probe-yes { color: var(--color-accent); }</style>
routes/examples/components/_snippets/prop-probe/usage.html
<p-prop-probe call='step="5" locked' step="5" locked></p-prop-probe><p-prop-probe call='locked="false" label="Hi"' locked="false" label="Hi"></p-prop-probe><p-prop-probe call="no attributes"></p-prop-probe>
Live result
- step="5" locked
step = 15 · numberlocked = falsetrue · booleanlabel = 'none'"none" · string
- locked="false" label="Hi"
step = 11 · numberlocked = falsefalse · booleanlabel = 'none'"Hi" · string
- no attributes
step = 11 · numberlocked = falsefalse · booleanlabel = 'none'"none" · string
- A number default turns
"5"into5. A boolean default turns a bare attribute or"true"intotrueand"false"intofalse. A string default keeps the text. Any other default (an object,null) takes the value as passed with:prop="path". - A missing attribute gives the default. HTML (
<if $locked>) and JS (locked) read the same converted value. - An attribute the script does not declare is an error at the call site (
html/unknown-prop), and assigning a prop isjs/prop-write.
Where a component lives decides its tag
Every component on this page sits in routes/examples/components/_components/, so it is a <p-…> visible to this folder and the folders below it. The lookup walks up from the page folder to routes/, so routes/_components/x/ is visible to every route. lib/components/x/ makes it <c-x> everywhere; promoting one is a move plus a rename from p- to c-.
p-names are private to their folder, styles included. This page and the syntax page each have their own<p-badge>; the build gives each one its owndata-cand scopes each<style>to it, so both write.badge-iconand never share a rule.- A
<p-x>used outsideroutes/is an error, and so are two components with the same folder name on one page (<c-card>plus<p-card>). - A component cannot have a
.server.js: its data comes from the page'sload, as in the list above. - A component cannot use itself, and its root cannot be
<template>,<slot>or another component. - A component's script loads only on pages that use it. Its
<style>goes into the single app stylesheet, scoped by itsdata-c.