@sveltery/ui

Add Sveltery UI components to a Svelte 5 app. The CLI copies each component's source into your project, so you own and edit it.

Requirements

• Svelte 5 with SvelteKit or Vite.
• Tailwind CSS 4. If your app does not use Tailwind yet, run npx sv add tailwindcss first.

Set up a project

npx @sveltery/ui@latest init

init asks for a style, an icon library and a base color. Then it:

• writes components.json,
• adds the theme tokens and the @sveltery/ui/tailwind.css import to your CSS file,
• installs cn, class-variance-authority, tw-animate-css, the icon package and @sveltery/ui, which ships the tailwind.css that your CSS imports.

Run it again at any time. A second run with the same choices leaves your files unchanged.

To start from a preset instead, pass --preset. It takes a preset name such as nova, a preset code from the Create page, or the URL of an /init item. A preset sets the style, icon library, base color, theme, fonts, radius and menu look, and its fonts install as fontsource packages. --preset with no value lists the presets, and Custom prints the Create page link.

npx @sveltery/ui@latest init --preset b0

| Option | Description | | --- | --- | | -y, --yes | Use the defaults (or the flags) without prompting. | | -p, --preset [name\|code\|url] | Use a preset. Cannot be combined with --style, --icons or --base-color. With -y and no value, uses nova. | | --style <name> | nova, vega, maia, lyra, mira, luma, sera or rhea. | | --icons <library> | lucide, tabler, hugeicons, phosphor or remixicon. | | --base-color <name> | neutral, stone, zinc, mauve, olive, mist or taupe. | | --css <path> | The CSS file that imports Tailwind. Defaults to src/app.css. | | --cwd <path> | The project root. Defaults to the current directory. | | --no-install | Do not install packages. |

Add components

npx @sveltery/ui@latest add button dialog

add fetches each component and the components it depends on. It shows the files it will write and the packages it will install, then asks you to continue. Files go to the aliases.ui directory in components.json, which is src/lib/components/ui by default.

If a file already exists and differs, add asks before it overwrites it. Identical files are skipped.

| Option | Description | | --- | --- | | -y, --yes | Do not ask to continue. Changed files are skipped unless you also pass -o. | | -o, --overwrite | Overwrite changed files without asking. | | -a, --all | Add every component. | | --dry-run | Show the plan and stop. | | --no-install | Do not install packages. | | --cwd <path> | The project root. Defaults to the current directory. |

An argument that is a URL is fetched as is, so you can add an item from another registry that uses the same format. An argument such as acme/ui/hello-card installs hello-card from the registry.json at the root of the public GitHub repository acme/ui. Add # and a branch, tag or commit, such as acme/ui/hello-card#v1.0, to read another ref.

See and apply upstream changes

npx @sveltery/ui@latest diff
npx @sveltery/ui@latest update

An item counts as installed when any of its files exists under aliases.ui. With no names, diff and update act on every installed item and the items they depend on. A named item that is not installed is an error.

diff [items...] prints a unified diff for each file that differs from the registry. Your file is the a/ side and the registry version is the b/ side, so + lines are what update would write. It ends with a count such as 3 files differ in 2 items, or Everything is up to date.. It never writes anything.

update [items...] plans the same files as add, including new files, new items an item now depends on and missing packages. For each changed file it shows the diff and asks whether to overwrite it. The default is no. New files are written without asking.

| Option | Description | | --- | --- | | -y, --yes | Overwrite changed files without asking. This discards your edits to them. | | --no-install | Do not install packages. | | --cwd <path> | The project root. Defaults to the current directory. |

Search the registry

npx @sveltery/ui@latest search @sveltery -q dialog

search (alias list) prints the items of the registries you name, with a type and a description. Searching @sveltery, the Sveltery UI registry, needs no components.json. With no registry, search searches every namespace in the registries of components.json except @sveltery.

| Option | Description | | --- | --- | | -q, --query <query> | Rank and keep the items that match the query in their name, title or description. | | -t, --type <type> | Keep one item type, such as ui or block. Comma-separate several. | | -l, --limit <number> | Show at most this many items. Defaults to 100. | | -o, --offset <number> | Skip this many items. Defaults to 0. | | --json | Print { pagination, items, errors } as JSON. errors lists the registries that a search of every registry skipped. | | --cwd <path> | The project root. Defaults to the current directory. |

Find a component's docs

npx @sveltery/ui@latest docs button dropdown-menu

docs prints, for each component, the links to its docs page (docs), the same page as Markdown with every example inlined (examples) and, for a component styled on a Base UI component, Base UI's API reference (api). Pass --json for { base, results }.

See how the CLI reads your project

npx @sveltery/ui@latest info

info prints the framework and the Svelte, SvelteKit and Tailwind CSS versions, your components.json settings, the preset code they add up to, where each alias points, and the registry items you installed. Pass --json for an object. It works without a components.json and never writes anything.

Read and share presets

npx @sveltery/ui@latest preset decode b4xFeBLg4O
npx @sveltery/ui@latest preset url b4xFeBLg4O
npx @sveltery/ui@latest preset open b4xFeBLg4O
npx @sveltery/ui@latest preset resolve

decode prints what a preset code sets (--json for an object), url prints its link on the Create page, and open opens that link in your browser. resolve (alias info) prints the preset that your components.json and CSS file add up to, with a * on each value your project does not show. None of them writes a file.

Use another registry

Set SVELTERY_REGISTRY_URL to the registry root, for example a preview deploy's /r URL. It takes precedence over the registry key in components.json.