# Nana UI > Nana-Tec Design System — a framework-agnostic web component library built with Lit. > Components are custom elements (``, ``, …) that work in > plain HTML, React, Vue, Svelte, or any framework that renders DOM. ## Install ```bash npm install @nana-tec/ui-components ``` Import the whole library, or just the elements you use: ```js import "@nana-tec/ui-components"; // everything import "@nana-tec/ui-components/button"; // one component ``` Every page below is available as Markdown at the same URL with a `.md` suffix. The entire documentation set in one file: https://design.nanatec.co.ke/llms-full.txt ## Overview - [Nana UI](https://design.nanatec.co.ke/index.md): A framework-agnostic web component library built with Lit — consistent APIs, dark mode, and full accessibility across React, Vue, Svelte, or vanilla JS. ## Guides - [Design Tokens](https://design.nanatec.co.ke/guides/design-tokens.md): The color, spacing, radius, shadow, typography, z-index, and transition scales that every Nana UI component is built from. - [Getting Started](https://design.nanatec.co.ke/guides/getting-started.md): Install @nana-tec/ui-components and render your first web component in any framework. - [Docs for LLMs](https://design.nanatec.co.ke/guides/llms.md): Every page of these docs is available as clean Markdown — one file per component, an llms.txt index, or the whole site in a single download. - [Reusability & Composition](https://design.nanatec.co.ke/guides/reusability.md): Consume Nana components through attributes, slots, and events — theme once, reuse everywhere. - [Theming](https://design.nanatec.co.ke/guides/theming.md): Customize Nana UI with design tokens, CSS custom properties, and dark mode. ## Components - [Alert](https://design.nanatec.co.ke/components/alert.md): A contextual message banner for feedback, status and important notices. Supports an optional title, a leading status icon, action buttons and a dismiss control. - [Animated Icon](https://design.nanatec.co.ke/components/animated-icon.md): A motion wrapper around Icon. It renders a real `` — inheriting the entire built-in glyph set, the shared icon registry and the accessibility wiring — and layers a CSS-driven animation on top, started by a trigger. - [Badge](https://design.nanatec.co.ke/components/badge.md): A small status indicator label with clean, modern design. - [Breadcrumb](https://design.nanatec.co.ke/components/breadcrumb.md): A navigation trail showing the user's location in a hierarchy. Compose it from `nana-breadcrumb-item` children; the last item is usually `current`. One element covers the common professional patterns through orthogonal attributes: - **Standard / Chevron / Path** — `separator` (`slash` · `chevron` · `arrow` · `dot`, or any custom glyph) and `variant="path"`. - **Pill · Card · Step** — `variant`. - **Truncated / Dropdown** — `max-items` collapses the middle into a `…`, either inline (`collapse="expand"`) or into a menu (`collapse="dropdown"`). - **Mobile compact / back-nav** — `responsive` collapses to `← Parent` below `compact-width`. - **Underlined** — `underline` emphasises the current page (composes with any variant). - [Breadcrumb Item](https://design.nanatec.co.ke/components/breadcrumb-item.md): A single step in a `nana-breadcrumb` trail. Renders as a link when `href` is set, otherwise as plain text. Mark the final step with `current` so it is announced as the current page and rendered as non-interactive text. Item variants compose through attributes: - **Icon / Icon-only** — slot a `nana-icon` into `prefix` (add `aria-label` when there is no text). - **Disabled / Loading** — `disabled`, `loading` (skeleton placeholder). - **Dropdown** — `dropdown` turns the item into a menu trigger; put the menu entries in the `menu` slot. - **Ellipsis** — `ellipsis` renders a static `⋯`. - **Status / Badge** — `status` (success·warning·error·info) and `badge`. The `data-*` attributes are driven by the parent `nana-breadcrumb` (variant, step index, collapse/compact state) — you normally don't set them by hand. - [Button](https://design.nanatec.co.ke/components/button.md): A clickable button (or link styled as a button) with variants, sizes, loading and icon support. - [Button Group](https://design.nanatec.co.ke/components/button-group.md): Groups related `nana-button` elements into a single visual unit — joined together (the default) or evenly spaced. Optionally propagates a shared `size` and `variant` to every button so they stay consistent. - [Card](https://design.nanatec.co.ke/components/card.md): A surface container that groups related content. Compose it with `nana-card-header`, `nana-card-title`, `nana-card-description`, `nana-card-content` and `nana-card-footer`. - [Carousel](https://design.nanatec.co.ke/components/carousel.md): A scroll-snap carousel. Compose it from `nana-carousel-item` slides and pick the navigation, layout and behaviour through attributes — one element covers basic, multi-item, card, gallery, hero and testimonial use-cases. Built on the native scroll container, so touch swipe, trackpad and momentum work for free; mouse drag, keyboard, autoplay and looping are layered on top. - [Carousel Item](https://design.nanatec.co.ke/components/carousel-item.md): A single slide inside a carousel. It is a thin, separately-importable wrapper that takes any content. The parent nana-carousel sizes it (slides-per-view / peek) and labels it ("3 of 8") for screen readers. - [Checkbox](https://design.nanatec.co.ke/components/checkbox.md): A form-associated checkbox. Works inside a native `
`, supports the indeterminate state, and offers `card` / `toggle` tile variants for selection UIs. - [Checkbox Group](https://design.nanatec.co.ke/components/checkbox-group.md): Groups related `nana-checkbox` elements under one label, lays them out, and propagates a shared `size`/`disabled`. Tracks the set of checked values and emits them on change. - [Color Picker](https://design.nanatec.co.ke/components/color-picker.md): A full-featured color selection component with alpha, swatches, multiple formats, an eyedropper, and a WCAG contrast checker. - [Combobox](https://design.nanatec.co.ke/components/combobox.md): An editable text field paired with a filterable listbox. Type to filter the `nana-option` children, then pick a value with the keyboard or pointer. The panel flips above the field when it would overflow the viewport. - [Copy Button](https://design.nanatec.co.ke/components/copy-button.md): A button that copies text to the clipboard and shows a brief "copied" confirmation. Copy a literal `value`, or read the text from another element via the `from` selector. Renders icon-only by default; set `show-label` to display the swapping Copy → Copied text. - [Date Range](https://design.nanatec.co.ke/components/date-range.md): A date-range picker: a trigger showing the current range, and a popover with one or two month grids plus optional shortcut presets. The form value is the two ISO dates joined by a slash (`2026-01-01/2026-01-31`), which is what `start`/`end` serialise to. An incomplete range submits nothing. - [Details](https://design.nanatec.co.ke/components/details.md): A disclosure / expandable panel. A clickable summary toggles a smoothly animated content region. Compose the body from any markup via the default slot, and add a leading `icon` or trailing `badge`. Group several together with a shared `name` for accordion behaviour (one open at a time). - [Dialog](https://design.nanatec.co.ke/components/dialog.md): A modal dialog built on the native `` element — so it gets the top layer, a backdrop, focus trapping and Escape-to-close for free. Compose it from `nana-dialog-header`, `nana-dialog-body` and `nana-dialog-footer`. - [Divider](https://design.nanatec.co.ke/components/divider.md): A separator between content or layout regions. Supports text/icon labels, line styles, thickness and orientation. - [Drawer](https://design.nanatec.co.ke/components/drawer.md): A panel that slides in from an edge, built on the native `` element. `temporary` (default) shows a modal with a backdrop and focus trap; `persistent` shows a non-modal panel that doesn't block the page. - [Dropdown](https://design.nanatec.co.ke/components/dropdown.md): A trigger that reveals a panel of options — single or multi-select, optionally searchable. Compose it from `nana-option` children (use `nana-menu-label` for groups). Flips above the trigger when it would overflow. - [Editor](https://design.nanatec.co.ke/components/editor.md): A rich text editor with a JSON document model, snapshot undo/redo, HTML/Markdown export, slash commands, and an extensible toolbar. - [Filter](https://design.nanatec.co.ke/components/filter.md): Collects a set of filter fields into one value, renders the active ones as removable chips, and publishes the result — the toolbar that sits above a data table. - [Filter Item](https://design.nanatec.co.ke/components/filter-item.md): Wraps one field component and reports its value to the surrounding filter — the bridge between any input and the aggregated filter value. - [Format Bytes](https://design.nanatec.co.ke/components/format-bytes.md): Formats a byte (or bit) value into a human-readable, locale-aware string, auto-scaling to the best unit (B → kB → MB → GB …). - [Format Date](https://design.nanatec.co.ke/components/format-date.md): Formats a date with `Intl` — relative ("2 days ago"), short/medium/long absolute, or ISO. - [Format Number](https://design.nanatec.co.ke/components/format-number.md): Formats a number with `Intl.NumberFormat` — decimal, currency or percent, with optional compact notation (1K / 1M) and fixed precision. - [Icon](https://design.nanatec.co.ke/components/icon.md): An SVG icon component backed by a built-in icon set. Accepts a `name` attribute to render a named icon, or a default slot for custom SVG content. - [Icon Button](https://design.nanatec.co.ke/components/icon-button.md): A compact, icon-only button. Renders a named `nana-icon` (or slotted icon) and requires a `label` for accessibility. - [Image Comparer](https://design.nanatec.co.ke/components/image-comparer.md): Compares two images (or any content) with a draggable slider, or a crossfade. - [Include](https://design.nanatec.co.ke/components/include.md): Fetches an external HTML file and renders it inline. Loads eagerly by default, or `lazy` to defer until it scrolls into view. - [Input](https://design.nanatec.co.ke/components/input.md): A text input with label, helper text, validation, prefix/suffix and clear support. - [Menu](https://design.nanatec.co.ke/components/menu.md): A menu / navigation list. Lays out `nana-menu-item` (and `nana-menu-label`) children, manages roving-tabindex keyboard navigation, and bubbles `nana-select` when an item is chosen. - [Menu Item](https://design.nanatec.co.ke/components/menu-item.md): An item within a `nana-menu`: icon + label + shortcut, with selected (checkmark), destructive, disabled and submenu states. Renders as a button, or a link when `href` is set, and bubbles `nana-select`. - [Menu Label](https://design.nanatec.co.ke/components/menu-label.md): A non-interactive section header inside a `nana-menu`. - [Menubar](https://design.nanatec.co.ke/components/menubar.md): An application-style menu bar — a horizontal row of `nana-menubar-menu` top-level menus (File, Edit, View…), each opening a dropdown of `nana-menu-item` rows. Implements the WAI-ARIA menubar pattern: roving tabindex across the triggers, arrow-key switching between menus (with the open panel following), hover-to-switch once a menu is open, and dismissal on outside click or Escape. - [Mutation Observer](https://design.nanatec.co.ke/components/mutation-observer.md): Watches its slotted content for DOM changes via `MutationObserver` and emits `nana-mutation` with the records. Useful for reacting to attribute, child-list, subtree or character-data changes without wiring observers by hand. - [Option](https://design.nanatec.co.ke/components/option.md): A selectable option for listbox / select / dropdown usage. Bubbles `nana-select` with its `value` and reflects `selected` / `disabled`. - [Pagination](https://design.nanatec.co.ke/components/pagination.md): A navigation control for paged data. It lives **beside** a table or list, never inside it. Controlled-by-attribute but self-updating: clicking moves the page (updating `page`) and emits `nana-page-change` so consumers can slice (client-side) or refetch (server-side). - [Popup](https://design.nanatec.co.ke/components/popup.md): A lightweight anchored popover. Positions floating content relative to an anchor (slotted into `anchor`), with placement, an optional arrow, and click / hover / manual triggers. Flips on the main axis when it would overflow the viewport. - [Progress Bar](https://design.nanatec.co.ke/components/progress-bar.md): A linear progress indicator — determinate or indeterminate, with optional label, stripes, sizes and semantic colours. - [Progress Ring](https://design.nanatec.co.ke/components/progress-ring.md): A circular progress indicator — determinate or indeterminate, with an optional centre label, sizes and semantic colours. - [QR Code](https://design.nanatec.co.ke/components/qr-code.md): Renders a QR code as crisp, scalable SVG. Encodes any text (byte mode, UTF-8) with a self-contained generator — no runtime dependencies. Choose a module style with `variant`, theme it with CSS custom properties, and drop a logo into the center via the default slot. - [Radio](https://design.nanatec.co.ke/components/radio.md): A single radio control — a circle + label. Selection is mutually exclusive and owned by the parent `nana-radio-group`, which manages the checked value, keyboard roving and form association; on its own a radio still renders and fires `nana-change`. Rebrand by overriding `--nana-radio-accent` (or the global `--nana-surface-accent`) — no need to fork the component. - [Range](https://design.nanatec.co.ke/components/range.md): A range/slider component supporting single and dual-thumb selection, vertical orientation, stepped and continuous modes, tooltips, tick marks, and linked numeric inputs. - [Rating](https://design.nanatec.co.ke/components/rating.md): A rating component for displaying and collecting star (or heart/dot) ratings. Supports fractional display, half- and full-step input, multiple symbols, read-only and disabled states, sizes, hover preview, keyboard control and an optional value label. - [Relative Time](https://design.nanatec.co.ke/components/relative-time.md): Renders a localised, auto-updating relative timestamp — "2 hours ago", "in 3 days" — from a date. It refreshes itself on a cadence proportional to the elapsed time (every second under a minute, every minute under an hour, and so on) and outputs a semantic `