Guides
Getting Started
Install @nana-tec/ui-components and render your first web component in any framework.
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.
Two ways to install
Section titled “Two ways to install”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-componentsCopy 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 initnpx @nana-tec/ui add buttonThe 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.
Importing components
Section titled “Importing components”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.
Subpath imports — no runtime fetching
Section titled “Subpath imports — no runtime fetching”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.
The barrel — everything at once
Section titled “The barrel — everything at once”import "@nana-tec/ui-components";Simplest, and the right choice for a prototype or a page that genuinely uses most of the library.
Which to use
Section titled “Which to use”Measured with esbuild for a page using four components:
| Import | Initial JS |
|---|---|
…/autoloader | 8 kB, plus only the components rendered |
| Four subpath imports | 128 kB |
| Four named imports from the barrel | 712 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>Without a bundler
Section titled “Without a bundler”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.
Styling
Section titled “Styling”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.
Framework usage
Section titled “Framework usage”Because these are native custom elements, they drop into any template.
Vanilla / HTML
Section titled “Vanilla / HTML”<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>;}Vue & Svelte
Section titled “Vue & Svelte”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>Next steps
Section titled “Next steps”- Theming — design tokens, CSS custom properties, and dark mode.
- Browse the components for API references and live examples.