Guides
Svelte
Nana UI for Svelte 5 — install @nana-tec/ui-svelte as a package, or copy the components into your project as source. Styled with Tailwind.
The Svelte components come two ways. Pick one per project:
| Install the package | Copy the source | |
|---|---|---|
| How | npm install @nana-tec/ui-svelte | npx @nana-tec/ui add <name> --framework svelte |
| Where the code lives | node_modules | your repository, under #lib/components/ui |
| Updates | bump the version | re-run add / update; edited files are left alone |
| Changing a component | class, themes and data-* selectors; anything deeper goes into Nana UI and ships as a release | edit the file — it is yours |
Install the package when several apps should look and behave the same and receive fixes together. Copy the source when a project needs to change a component in ways the props do not cover.
Install the package
Section titled “Install the package”@nana-tec/ui-svelte is published to GitHub Packages with the rest of the
@nana-tec scope, so the project needs an .npmrc that can read it. The token
needs the read:packages scope, locally, in CI and on any server that installs:
@nana-tec:registry=https://npm.pkg.github.com//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}Keep the token in the environment, not in the file, and keep .npmrc out of git
if it ever holds one.
npm install @nana-tec/ui-svelte @nana-tec/ui-themes@nana-tec/ui-core, @nana-tec/ui-dom, clsx and tailwind-merge come with
it; svelte 5 is a peer dependency. The package ships compiled .svelte files
and type declarations in dist, so your tsconfig does not compile the
library.
Styles
Section titled “Styles”Import Tailwind, the theme and the package’s Tailwind mapping once, in the
stylesheet your root layout loads. Tailwind does not scan node_modules, so
point @source at the package or its classes never reach the page:
@import "tailwindcss";@import "@nana-tec/ui-themes/base";@import "@nana-tec/ui-svelte/styles/nana-theme.css";@source "../node_modules/@nana-tec/ui-svelte/dist";
body { background: var(--nana-surface-bg); color: var(--nana-surface-text);}@source is relative to the stylesheet. For src/app.css in a SvelteKit app it
is ../node_modules/...; in a monorepo, point it at the node_modules of the
workspace that depends on the package.
Using the components
Section titled “Using the components”Every component is exported from the package root, named with the Nana
prefix:
<script lang="ts"> import { NanaButton } from "@nana-tec/ui-svelte";</script>
<NanaButton variant="primary">Save</NanaButton>Each component also has its own entry point, and the blocks are reached only that way, because a block’s types can share a name with a component’s:
import { NanaTable, NanaTableRow } from "@nana-tec/ui-svelte/components/table";import { NanaLoginForm } from "@nana-tec/ui-svelte/blocks/login-form";import { cn } from "@nana-tec/ui-svelte/utils/cn";The usage examples on each component page import from
#lib/components/ui/<name>/index.js, which is where the copied source lands;
with the package, import the same names from @nana-tec/ui-svelte.
Updating
Section titled “Updating”Bump @nana-tec/ui-svelte with the other @nana-tec packages, and keep them on
the same version — the components and the rules in ui-core are released
together.
Copy the source
Section titled “Copy the source”npx @nana-tec/ui init --framework sveltenpx @nana-tec/ui add button dialog --framework svelteinit finds your import alias. SvelteKit 3 declares #lib in package.json
imports, and components land under #lib/components/ui; SvelteKit 2 keeps
$lib. If a SvelteKit 3 project has no #lib yet, init tells you the line to
add:
"imports": { "#lib/*": "./src/lib/*" }Import the theme once, after Tailwind v4, and give the page its background so dark mode reaches the whole page:
@import "tailwindcss";@import "@nana-tec/ui-themes/base";@import "#lib/nana-ui/styles/nana-theme.css";
body { background: var(--nana-surface-bg); color: var(--nana-surface-text);}Every component page has a Svelte tab beside the web component one: pick it once
and the previews, installation, usage and props follow it across the site.
Components are named with the Nana prefix — NanaButton, NanaDialog.
On SvelteKit 2, write $lib where this page writes #lib. The usage examples
import from $lib/components/ui/<name>; on SvelteKit 3 that is
#lib/components/ui/<name>/index.js, because subpath imports name a file rather
than a folder.
Changing the look
Section titled “Changing the look”The components read every colour, radius and surface from --nana-* variables,
so a new theme is a stylesheet and touches no component. Import it after the base, then name it on the root with data-theme — see
Writing a theme. For one instance, pass
class: it is merged with the component’s own classes and wins. With copied
source, the class maps in nana-ui/styles are yours to edit for anything
deeper; update leaves a file you have changed alone unless you pass --force.
With the package, the class maps are not yours to edit — a change every app
needs belongs in Nana UI and arrives in a release.
Every element also carries data-nana, data-part and data-state, so plain CSS
outside a cascade layer can reach it without editing anything:
[data-nana="tabs"][data-part="tab"][data-state="active"] { text-decoration: underline;}