# Svelte

> Source: https://design.nanatec.co.ke/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

`@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:

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

```bash
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

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:

```css
@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

Every component is exported from the package root, named with the `Nana`
prefix:

```svelte
<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:

```ts
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

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

```bash
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:

```json
"imports": { "#lib/*": "./src/lib/*" }
```

Import the theme once, after Tailwind v4, and give the page its background so
dark mode reaches the whole page:

```css
@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

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](/guides/theming/#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:

```css
[data-nana="tabs"][data-part="tab"][data-state="active"] {
  text-decoration: underline;
}
```
