Installation

5h3ll-ui can be used from a CDN or installed with npm. Use the CDN for simple static pages and prototypes. Use npm when your project already has a Tailwind CSS build step.

CDN

Add the stylesheet

Use the default bundled stylesheet. It is an alias for the Vega style bundle.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/5h3ll-ui@0.1.5/dist/5h3ll-ui.cdn.min.css" />

You can also use one of the named style bundles: vega, nova, maia, lyra, mira, luma, sera, or rhea.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/5h3ll-ui@0.1.5/dist/5h3ll-ui-maia.cdn.min.css" />

Add JavaScript when needed

Most components are CSS-only. Interactive components need JavaScript. Use the all-in-one bundle when file size is not a concern.

<script src="https://cdn.jsdelivr.net/npm/5h3ll-ui@0.1.5/dist/js/all.min.js" defer></script>

Or load the 5h3ll-ui runtime once, then only the component scripts you use.

<script src="https://cdn.jsdelivr.net/npm/5h3ll-ui@0.1.5/dist/js/5h3ll-ui.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/5h3ll-ui@0.1.5/dist/js/dropdown-menu.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/5h3ll-ui@0.1.5/dist/js/select.min.js" defer></script>

Use the markup

<button class="btn">Button</button>
<div class="card">
  <header>
    <h3>Card title</h3>
    <p>Card description.</p>
  </header>
  <section>Card content.</section>
</div>

Icons are not bundled

5h3ll-ui examples use inline Lucide SVGs, but 5h3ll-ui does not ship an icon package. Copy SVGs into your markup or install your preferred icon library. See Customization > Icons.

CDN files

File	Description
`dist/5h3ll-ui.cdn.min.css`	Default standalone CDN stylesheet. Alias for the Vega style.
`dist/5h3ll-ui-{style}.cdn.min.css`	Standalone CDN stylesheet for `vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera`, or `rhea`.
`dist/5h3ll-ui-base.cdn.min.css`	Base tokens, utilities, and component structure without a style pack.
`dist/5h3ll-ui-compat.cdn.min.css`	Optional pre-1.0 compatibility aliases. Load after 5h3ll-ui.
`dist/js/all.min.js`	All auto-initialized JavaScript components except Chart.
`dist/js/5h3ll-ui.min.js`	Runtime only. Load once before individual component scripts.
`dist/js/{component}.min.js`	Individual JavaScript component file.

NPM

Install Tailwind CSS

5h3ll-ui is authored for Tailwind CSS. Install Tailwind first if your project does not already use it.

Follow the Tailwind CSS installation guide.

Install 5h3ll-ui

npm install 5h3ll-ui

pnpm add 5h3ll-ui

bun add 5h3ll-ui

yarn add 5h3ll-ui

If you are not using a bundler, copy or serve the files you need from node_modules/5h3ll-ui/dist.

Add CSS

Include one 5h3ll-ui stylesheet after your Tailwind CSS. The default stylesheet is an alias for the Vega style bundle.

<link rel="stylesheet" href="/assets/5h3ll-ui.css" />

You can also use one of the named style bundles: vega, nova, maia, lyra, mira, luma, sera, or rhea.

<link rel="stylesheet" href="/assets/5h3ll-ui-maia.css" />

If your build tool supports CSS package imports, import Tailwind and then one 5h3ll-ui bundle.

@import "tailwindcss";
@import "5h3ll-ui";

Or import a named style bundle.

@import "tailwindcss";
@import "5h3ll-ui/maia";

Stylesheet order matters

Load 5h3ll-ui after any stylesheet that includes Tailwind base/preflight. Loading another full Tailwind build after 5h3ll-ui can reset borders, inputs, and other component defaults.

Add JavaScript when needed

Most components are CSS-only. Interactive components need JavaScript. Include the all-in-one script when file size is not a concern.

<script src="/assets/js/all.min.js" defer></script>

Or include the 5h3ll-ui runtime once, then only the component scripts you use.

<script src="/assets/js/5h3ll-ui.min.js" defer></script>
<script src="/assets/js/dropdown-menu.min.js" defer></script>
<script src="/assets/js/select.min.js" defer></script>

If your build tool supports JavaScript package imports, use the all-in-one import:

import "5h3ll-ui/all";

Or import the runtime once, then individual components.

import "5h3ll-ui/5h3ll-ui";
import "5h3ll-ui/dropdown-menu";
import "5h3ll-ui/select";

Templates

5h3ll-ui ships optional Nunjucks and Jinja templates with 5h3ll-ui.

If you previously used 5h3ll-ui-cli, install 5h3ll-ui instead and copy the template files from the package.

cp -R node_modules/5h3ll-ui/templates/nunjucks ./templates/5h3ll-ui

cp -R node_modules/5h3ll-ui/templates/jinja ./templates/5h3ll-ui

See Templates for the available macros and arguments.

CSS imports

Import	Description
`5h3ll-ui`	Default full stylesheet. Alias for `5h3ll-ui/vega`.
`5h3ll-ui/{style}`	Full stylesheet for `vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera`, or `rhea`.
`5h3ll-ui/base`	Base tokens, utilities, and component structure without a style pack. Use this before a custom style.
`5h3ll-ui/components`	All component structure without a style pack.
`5h3ll-ui/components/button`	Individual component CSS. Replace `button` with any component file.
`5h3ll-ui/styles/maia`	Individual style-pack CSS. Use with `5h3ll-ui/base` or `5h3ll-ui/components`.
`5h3ll-ui/all.css`	Full default stylesheet plus all style-pack CSS. Use only when you need every style pack available at runtime.
`5h3ll-ui/compat`	Optional pre-1.0 compatibility aliases. Load after 5h3ll-ui.

Template files

Path	Description
`node_modules/5h3ll-ui/templates/nunjucks`	Nunjucks templates.
`node_modules/5h3ll-ui/templates/jinja`	Jinja templates.

JavaScript imports

Import	Description
`5h3ll-ui/all`	All auto-initialized JavaScript components except Chart.
`5h3ll-ui/5h3ll-ui`	Runtime only. Import once before individual component scripts.
`5h3ll-ui/chart`	Chart helper. Load Chart.js separately.
`5h3ll-ui/combobox`	Combobox controller.
`5h3ll-ui/command`	Command controller.
`5h3ll-ui/drawer`	Drawer controller.
`5h3ll-ui/dropdown-menu`	Dropdown Menu controller.
`5h3ll-ui/popover`	Popover controller.
`5h3ll-ui/range`	Slider/range controller.
`5h3ll-ui/select`	Select controller.
`5h3ll-ui/sidebar`	Sidebar controller.
`5h3ll-ui/tabs`	Tabs controller.
`5h3ll-ui/toast`	Toast controller.

JavaScript components

These components need JavaScript for behavior:

Chart uses a separate helper and is not included in 5h3ll-ui/all.

Each component page shows the minimal scripts or imports required for that component.

JavaScript lifecycle

5h3ll-ui initializes registered components on page load and when new DOM is inserted.

Use window['5h3ll-ui'].initAll() after manually inserting HTML that contains 5h3ll-ui components. It only initializes components that are not already initialized.

Use window['5h3ll-ui'].initAll({ force: true }) when a framework or navigation library restores previously initialized DOM from a cache, such as an HTMX history restore. Force mode destroys existing component instances before reinitializing them, so it also resets transient state such as open menus, focus state, and active interactions.

Compatibility

5h3ll-ui 1.0 introduces new style packs and a smaller public API based on root classes plus semantic HTML and documented attributes. If you need pre-1.0 class aliases while migrating, load the compatibility stylesheet after your 5h3ll-ui stylesheet.

@import "tailwindcss";
@import "5h3ll-ui";
@import "5h3ll-ui/compat";

The compatibility stylesheet is intended for the default 5h3ll-ui style. It is not a separate style pack.