Skip to content
Nana UI

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.

View .md Download

The Svelte components come two ways. Pick one per project:

Install the packageCopy the source
Hownpm install @nana-tec/ui-sveltenpx @nana-tec/ui add <name> --framework svelte
Where the code livesnode_modulesyour repository, under #lib/components/ui
Updatesbump the versionre-run add / update; edited files are left alone
Changing a componentclass, themes and data-* selectors; anything deeper goes into Nana UI and ships as a releaseedit 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.

@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.

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.

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.

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.

npx @nana-tec/ui init --framework svelte
npx @nana-tec/ui add button dialog --framework svelte

init 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.

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;
}