Installation

PreviousNext

Add Hel UI to a React project in a few minutes.

Hel UI ships as one package, @hel/ui. You install it once and import components from it.

Requirements

  • React 19 or newer
  • Tailwind CSS v4
  • A bundler that can import CSS, such as Vite or Next.js

Set up

Point your project at the registry

@hel/ui is published to our own npm registry instead of the public one. Tell your package manager where to find the @hel scope by adding a line to the .npmrc file in your project:

.npmrc
@hel:registry=https://npm.kakontechnology.com/

Then log in with the account you were given:

npm login --registry https://npm.kakontechnology.com/ --scope=@hel

Install the package

pnpm add @hel/ui

Import the styles

Add these lines to your main CSS file, after Tailwind:

app.css
@import "tailwindcss";
@import "@hel/ui/styles.css";
@import "@hel/ui/fonts.css";

styles.css brings in the tokens and both themes, and it tells Tailwind to scan the library so the classes the components use are generated. fonts.css loads Inter, plus IBM Plex Sans Arabic for Arabic text. It is a separate file on purpose. If you use your own fonts, leave it out and nothing extra is downloaded.

Add the provider

HelProvider sets up the theme, the configuration, the text direction and the rest in the right order. Wrap your app with it once, near the root:

main.tsx
import { HelProvider } from "@hel/ui/provider"
 
export function Root({ children }: { children: React.ReactNode }) {
  return <HelProvider>{children}</HelProvider>
}

Use a component

Every component has its own import path:

import { Button } from "@hel/ui/button"
 
export function Example() {
  return <Button>Save changes</Button>
}

Next.js

The library files are not marked with "use client". In the App Router, render HelProvider from a file that starts with "use client", and do the same for any component you use that holds state, like a select or a dialog.

app/providers.tsx
"use client"
 
import { HelProvider } from "@hel/ui/provider"
 
export function Providers({ children }: { children: React.ReactNode }) {
  return <HelProvider>{children}</HelProvider>
}

Light and dark mode

Dark is the default theme. HelProvider includes a ThemeProvider, which follows the system setting, remembers the visitor's choice and sets a data-theme attribute on the page. To start in a specific theme, or to change where the choice is stored, pass theme props:

<HelProvider theme={{ defaultTheme: "light", storageKey: "my-app-theme" }}>
  {children}
</HelProvider>

Make it yours

Colors, spacing and type all come from the tokens, so you can restyle the library without touching a component. Override a token in your own CSS, after the Hel UI import, and everything that uses it updates. The Configuration page covers the config, fonts, the token layers and how to add a theme.