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

Steps of 5
10
Shift-click moves ten steps. Each click runs a function that assigns count; the runtime reapplies only the bindings, it never rebuilds the DOM.
  • export let start = 0 declares a prop with a default. The default's type converts the attribute: start="10" arrives as the number 10, so no Number() anywhere. Props are read-only: let count = start copies 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 read event.shiftKey. Assigning count schedules one render per microtask; there is no setState and no this.
  • With parentheses the function gets only what you list: paths, literals, event and el, 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-step only 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-step is still this component's buttons), and the root itself is [data-c="counter"]. A separate counter.css works the same way; having both it and the <style> (or a <script> and a counter.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.

0 likes

Empty panel

Nothing here yet.

Filling a slot the component does not declare is a check error (html/component).

<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
The list comes from load() in _plugins.server.js; the filter is a function of the page script over data.

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

New default text Beta caller text
The first badge falls back to the slot's default text; the second passes its own.

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 · number
locked = falsetrue · boolean
label = 'none'"none" · string
locked="false" label="Hi"
step = 11 · number
locked = falsefalse · boolean
label = 'none'"Hi" · string
no attributes
step = 11 · number
locked = falsefalse · boolean
label = 'none'"none" · string
Each probe declares the same three props and prints what its script receives: the value and its typeof.
  • A number default turns "5" into 5. A boolean default turns a bare attribute or "true" into true and "false" into false. 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 is js/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 own data-c and scopes each <style> to it, so both write .badge-icon and never share a rule.
  • A <p-x> used outside routes/ 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's load, 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 its data-c.