Skip to content
Nana UI

Guides

Getting Started

Install @nana-tec/ui-components and render your first web component in any framework.

View .md Download

Nana UI is a library of headless components built with Lit. Each one brings its behaviour — keyboard support, focus management, ARIA, form participation — and leaves the look to you. They are standards-based custom elements, so they work across any framework — React, Vue, Svelte, or vanilla JavaScript — with consistent APIs, events, and slots.

When you would rather start from a finished design, the Nana theme styles every component in one import; see Styling.

Pick one before you go further, because they lead to different files.

Install the package for a versioned dependency: upgrades arrive with npm update, and the component internals stay ours. This is the right default, and most projects should stop here.

npm install @nana-tec/ui-components

Copy the source in when you need to change a component’s internals, using the CLI. You own the files afterwards, and stop receiving updates automatically.

npx @nana-tec/ui init
npx @nana-tec/ui add button

The CLI serves components written natively for your framework — a .tsx on React, a .svelte on Svelte, a custom element otherwise — so what lands in your repository is idiomatic rather than wrapped. It detects which from your project.

Either way the design tokens stay on npm, so a palette is never frozen per project. The rest of this page covers the package; see Owning the Source for the CLI.

Three ways in, and they mix freely. All of them assume the installed package — components copied in by the CLI are imported from your own paths instead.

Autoloader — one import, smallest payload

Section titled “Autoloader — one import, smallest payload”
import "@nana-tec/ui-components/autoloader";

That is the only import you need. Every <nana-*> tag then works wherever it appears, including markup added later by a route change or innerHTML, and each component is fetched only when a page actually renders it.

Pair it with a rule so elements do not paint unstyled while their chunk is in flight:

:not(:defined) { visibility: hidden; }

:not(:defined) only ever matches custom elements awaiting upgrade, so it cannot affect ordinary markup.

import "@nana-tec/ui-components/button";
import "@nana-tec/ui-components/color-picker";

Everything is in the initial bundle, so nothing loads late. Best for the handful of components above the fold; let the autoloader cover the rest.

import "@nana-tec/ui-components";

Simplest, and the right choice for a prototype or a page that genuinely uses most of the library.

Measured with esbuild for a page using four components:

ImportInitial JS
…/autoloader8 kB, plus only the components rendered
Four subpath imports128 kB
Four named imports from the barrel712 kB

That last row is why the package exports classes but not short aliases like Button. Registering an element is a side effect, so a barrel that re-exports every component can never be tree-shaken — import { NanaButton } from "@nana-tec/ui-components" is correct and works, but it pulls the whole library. Use the autoloader or a subpath import when size matters.

Once imported, use the custom element anywhere in your markup:

<nana-button variant="primary">Save changes</nana-button>

The package also ships dist/nana-ui.iife.js, one minified script that registers every component and exposes the exports on a global NanaUI. Copy it from node_modules/@nana-tec/ui-components/dist/ to your own static files and load it with a plain script tag:

<script src="/vendor/nana-ui.iife.js"></script>

It carries the whole library, so prefer the autoloader whenever there is a bundler. The package is published to GitHub Packages, which public CDNs such as jsDelivr and unpkg cannot read, so there is no hosted URL: serve the file yourself.

Components arrive unstyled: they lay out what their behaviour needs — an open panel, a calendar grid, a slider track — and nothing more. They also clear the browser’s own defaults inside themselves (list bullets, heading margins, button borders), since your page’s CSS reset cannot reach into a shadow root. Style them your way, or switch on the Nana theme.

Your own design. Style each component through its parts and state attributes, listed on its reference page:

nana-button::part(base) {
padding: 0.5rem 1rem;
border-radius: 0.5rem;
background: #0f766e;
color: white;
}
nana-button[disabled]::part(base) {
opacity: 0.5;
}

States are part names too, so a selected day, an active page or an open panel is styled by naming both:

nana-calendar::part(day) { border-radius: 9999px; }
nana-calendar::part(day selected) { background: #0f766e; color: white; }
nana-calendar::part(day outside) { opacity: 0.4; }

Each part and the states it carries are listed under CSS parts on the component’s page.

The Nana theme. One import styles every component and brings the design tokens it is built from:

import "@nana-tec/ui-components/theme";

Change the look by setting any --nana-* token in your own CSS; your value wins wherever it sits in your stylesheets:

:root {
--nana-surface-accent: #1f5f4a;
}

To use the tokens in your own CSS before any script runs, or to get the type scale on body, also import the stylesheet:

@import "@nana-tec/ui-themes/base";

With the script-tag build, call NanaUI.enableNanaTheme() once the script has loaded. The theme can sit under your own rules — a ::part() rule of yours wins over the theme’s for the same property — so it also works as a starting point.

Because these are native custom elements, they drop into any template.

<script type="module">
import "@nana-tec/ui-components/button";
</script>
<nana-button variant="primary">Click me</nana-button>

React 19 renders the elements directly. Add @nana-tec/ui-components/jsx to compilerOptions.types so <nana-*> tags type-check:

import "@nana-tec/ui-components/button";
export function Save() {
return <nana-button variant="primary">Save</nana-button>;
}

Vanilla tags work directly; the package augments the framework’s template types so <nana-*> tags type-check:

import "@nana-tec/ui-components";
<script>
import "@nana-tec/ui-components/button";
</script>
<nana-button variant="primary">Click me</nana-button>
  • Theming — design tokens, CSS custom properties, and dark mode.
  • Browse the components for API references and live examples.