Docs Start
Installation
Install the packages, add the Vite plugin, import the stylesheets, then write the markup.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Requirements
| Tool | Range | Notes |
|---|---|---|
| Node | ^20.19.0 || >=22.12.0 | For the build (the engines of @svelte-lean/vite). The
repository needs >=22.18.0 and develops on 22.23.4. |
| Svelte | ^5.20.0 | Peer of @svelte-lean/table; the primitives have no framework dependency.
Tested with 5.57.1. |
| Vite | ^6.0.0 || ^7.0.0 || ^8.0.0 | Peer of @svelte-lean/vite. Tested with 7.3.6 and, nightly,
the latest release; Vite 6 is in the range and not tested. |
| TypeScript | 5 | moduleResolution bundler or node16. SvelteKit is
optional. |
Read from the package files at build time; the full matrix is on Compatibility.
Packages
npm install @svelte-lean/primitivespnpm add @svelte-lean/primitivesyarn add @svelte-lean/primitivesbun add @svelte-lean/primitivesnpm install @svelte-lean/stylespnpm add @svelte-lean/stylesyarn add @svelte-lean/stylesbun add @svelte-lean/stylesnpm install --save-dev @svelte-lean/vitepnpm add -D @svelte-lean/viteyarn add -D @svelte-lean/vitebun add -d @svelte-lean/vitenpm install @svelte-lean/tablepnpm add @svelte-lean/tableyarn add @svelte-lean/tablebun add @svelte-lean/tablenpm install @svelte-lean/querypnpm add @svelte-lean/queryyarn add @svelte-lean/querybun add @svelte-lean/query- Every primitive is a subpath export of
@svelte-lean/primitives. @svelte-lean/stylesis optional and ships CSS only.@svelte-lean/corecomes with the primitives package.@svelte-lean/query(server state) is independent of the others and versioned on its own: Client setup.- All packages are ESM-only with strict
exportsmaps.
Vite plugin
// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { svelteLean } from '@svelte-lean/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [svelteLean(), sveltekit()]
});// vite.config.ts, plain Vite without SvelteKit
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { svelteLean } from '@svelte-lean/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [svelteLean(), svelte()]
});- Place
svelteLean()beforesveltekit(), so the scanner reads the source before any preprocessor. - In development it keeps
@svelte-lean/primitivesand@svelte-lean/coreout of dependency pre-bundling, so the first page with a behavior does not force a reload. - Server transforms are skipped (
ssr: 'skip'); registration modules touch neitherdocumentnorwindowat evaluation. Every route of this site is prerendered with this configuration.
Styles
// src/routes/+layout.svelte
import '@svelte-lean/styles/tokens.css'; // required by every primitive file
import '@svelte-lean/styles/base.css'; // required by every primitive file
import '@svelte-lean/styles/dialog.css';
import '@svelte-lean/styles/tabs.css';
import '@svelte-lean/styles/menu.css'; // imports popover.css itself// Convenience only: every stylesheet, for prototypes
import '@svelte-lean/styles';- Every file declares the same cascade layer order, so the order between primitive files does not matter.
- Dependencies:
menu.cssandmenubar.cssneedpopover.css;button-group.cssneedsbutton.css. Each primitive page lists its stylesheets in order. - Selectors are wrapped in
:where(): any unlayered rule of the application wins. - Dark values apply under
prefers-color-scheme: darkordata-theme="dark"on the root.
First component
Native markup
A Tier 0 primitive is platform markup: nothing is imported, the browser owns the behavior, and
the data-slean attributes are hooks for the stylesheet and development validation.
<button type="button" commandfor="settings" command="show-modal">Settings</button>
<dialog id="settings" data-slean="dialog" aria-labelledby="settings-title">
<header>
<h2 id="settings-title">Settings</h2>
</header>
<div>…</div>
<footer>
<button type="button" commandfor="settings" command="close">Close</button>
</footer>
</dialog>The native-only fixture ships 0 B of Svelte Lean JavaScript. Missing platform features are covered on Browser support.
Behavior markup
Tabs need JavaScript the browser does not provide. Write the contract markup with a static marker; the plugin appends the registration import to the compiled module.
<!-- src/routes/settings/+page.svelte -->
<div data-slean="tabs" data-slean-value="account">
<div role="tablist" aria-label="Settings" data-slean-part="list">
<button
type="button"
id="tab-account"
role="tab"
aria-controls="panel-account"
aria-selected="true"
tabindex="0"
data-slean-part="trigger"
data-slean-value="account"
>
Account
</button>
<button
type="button"
id="tab-security"
role="tab"
aria-controls="panel-security"
aria-selected="false"
tabindex="-1"
data-slean-part="trigger"
data-slean-value="security"
>
Security
</button>
</div>
<div
id="panel-account"
role="tabpanel"
aria-labelledby="tab-account"
data-slean-part="panel"
data-slean-value="account"
>
…
</div>
<div
id="panel-security"
role="tabpanel"
aria-labelledby="tab-security"
data-slean-part="panel"
data-slean-value="security"
hidden
>
…
</div>
</div>// What the compiled module of that page receives from the plugin, appended after the
// compiled code (imports are hoisted, so it evaluates first):
import '@svelte-lean/primitives/tabs/register';A hundred files with tabs still bundle one registration module. Tabs-only fixture: 1839 B brotli.
Manual registration
Without the plugin, with a dynamic marker such as data-slean={kind}, or outside
Vite, import the registration module once on the client.
// src/routes/+layout.svelte (or any module that runs once on the client)
import '@svelte-lean/primitives/tabs/register';It is the module the plugin injects, and registration is idempotent, so mixing both is safe. Manual-registration fixture: 1839 B brotli, plugin path: 1839 B brotli, with the same module set asserted by both fixtures.
Events in Svelte
Behaviors emit cancelable DOM events on their root (slean:change, slean:select, slean:toggle, and the others each contract lists). In
Svelte 5, onslean:change={…} is a listener on that element, removed with it.
<!-- src/routes/settings/+page.svelte -->
<script lang="ts">
let subscribed = $state(false);
</script>
<div
data-slean="tabs"
data-slean-value="account"
onslean:change={(event) => {
// detail is the union of every change detail; behavior narrows it.
if (event.detail.behavior !== 'tabs') return;
if (event.detail.value === 'billing' && !subscribed) event.preventDefault();
}}
>
…
</div>Two one-time settings:
- The types-only entry
@svelte-lean/primitives/svelte-elementstypesevent.detail(narrowed by itsbehaviorfield) and failssvelte-checkon a misspelled event. It also typesdata-sleanwhere attributes are checked as props, such as rest props forwarded to an element. - The compiler warns on every attribute name with a colon (
attribute_illegal_colon).@svelte-lean/vitedrops it foronslean:in builds and the dev server;svelte-checkreadssvelte.config.js, so compose the same filter there.
// src/app.d.ts
/// <reference types="@svelte-lean/primitives/svelte-elements" />
declare global {
namespace App {}
}
export {};// svelte.config.js
import { withSleanWarningFilter } from '@svelte-lean/vite';
export default {
compilerOptions: {
// onslean:change listens to slean:change; the compiler warns about every attribute name
// with a colon. The Vite plugin drops the warning for onslean: in builds; svelte-check
// reads this file. Pass your own filter to compose it.
warningFilter: withSleanWarningFilter()
}
};Table
A Svelte component with three required props and a stylesheet; no runtime, no plugin.
<script lang="ts">
import { DataTable, type Column } from '@svelte-lean/table';
import '@svelte-lean/table/style.css';
type Member = { id: number; name: string; revenue: number };
const data: Member[] = [
{ id: 1, name: 'Amara Okafor', revenue: 1200 },
{ id: 2, name: 'Jonas Lindqvist', revenue: 9119 }
];
const columns: Column<Member>[] = [
{ id: 'name', header: 'Member' },
{ id: 'revenue', header: 'Revenue', align: 'end' }
];
</script>
<DataTable {data} {columns} getRowId={(row) => row.id} />Grouping, pivot, clipboard, CSV export, server data and persisted state are separate entry points. Next: Getting started.
Owned styles
Copy a primitive's stylesheet into the application and edit it; the behavior stays in the
package, so runtime accessibility fixes still arrive through npm (ADR 0005). There is no slean add command yet.
# Mode C today: copy the file and own it. The behavior stays in the package.
cp node_modules/@svelte-lean/styles/css/tabs.css src/lib/styles/tabs.css// The copied file keeps depending on the tokens; the behavior is still registered
// by the plugin (or by the manual import), not copied.
import '@svelte-lean/styles/tokens.css';
import '@svelte-lean/styles/base.css';
import '$lib/styles/tabs.css';Modes, layers and variants: Styling.
Build verification
A production build writes node_modules/.svelte-lean/manifest.json: each behavior
found, its module and the files that use it. report: true prints a summary.
// vite.config.ts
export default defineConfig({
plugins: [svelteLean({ report: true }), sveltekit()]
});svelte-lean build report
native-only button, dialog
runtime tabs -> @svelte-lean/primitives/tabs/register
src/routes/settings/+page.svelte
unknown none
dynamic none
manifest node_modules/.svelte-lean/manifest.jsonThe report lists what the scan saw; sizes and listener counts come from the consumer fixtures. The proof page shows this site's manifest.