Skip to content
Lenso UI

Quick Start

Get started with HeroUI v3 in minutes

Local runtime setup

Install the React components, compiled styles, and StyleX. This local derivation does not use the upstream Tailwind or HeroUI MCP installation flow.

pnpm add @lenso/ui @lenso/tokens @stylexjs/stylex

Import the compiled stylesheet once in your application entry or root layout:

import "@lenso/tokens";

Use native interaction contracts. For example:

"use client";
import { Button } from "@lenso/ui";

export function SaveButton() {
  return <Button onClick={() => console.log("Save activated")}>Save</Button>;
}

Configure your bundler's StyleX compiler for authored overrides. This documentation app uses next build --webpack and next dev --webpack with @stylexjs/unplugin, with CSS layers disabled.

import * as stylex from "@stylexjs/stylex";
import { tokens } from "@lenso/tokens/tokens.stylex.const";

const styles = stylex.create({
  panel: {
    backgroundColor: tokens.surface,
    color: tokens.surfaceForeground,
    borderRadius: tokens.radius,
    padding: 24,
  },
});

Ordinary controls use disabled, onClick, and native Base UI value contracts. Date, time, and color controls retain their explicit local React Aria parts; use DateField.Label, TimeField.Label, or ColorField.Label rather than the ordinary Field label.

Pinned upstream reference

Requirements

Quick Install

Prefer to let your AI assistant do it? Install the HeroUI MCP Server in your editor, then paste the prompt into your AI assistant — it will analyze your project and handle the entire setup for you.

Historical upstream prompt. Its MCP and Tailwind setup does not describe the local runtime.

Read the historical prompt
Set up HeroUI in this React project.

Use the HeroUI MCP server (@heroui/react-mcp) as the single source of truth for installation steps, peer dependencies, and component APIs. Start by retrieving the latest quick-start / installation guide from the MCP and follow it precisely — do not rely on memory for versions, package names, or setup steps.

Before making any changes:

1. Analyze the project. Detect the package manager (npm / pnpm / yarn / bun), framework (e.g. Next.js, Vite, Remix, Astro, etc.), TypeScript usage, and the location of the main CSS entry file (e.g. globals.css, app.css, index.css).
2. Confirm the project meets the requirements: React 19+ and Tailwind CSS v4. If Tailwind CSS v4 is not installed, set it up following the official Tailwind v4 framework guide that matches the detected framework before adding HeroUI.
3. Read package.json and only install what is missing. Pin to the exact versions listed in the MCP quick-start to avoid compatibility issues.

Then apply the setup:

- Install @lenso/ui and @lenso/tokens plus any missing mandatory peer dependencies.
- In the main Tailwind CSS entry file, add `@import "@lenso/tokens";` immediately after `@import "tailwindcss";`. Import order matters — tailwindcss must be imported first.
- Make sure the CSS entry file is loaded by the app (e.g. imported in the root layout / entry file for Next.js, Vite, Remix, etc.). HeroUI v3 does not require a Provider, so no wrapper component is needed.
- Add a small smoke test by rendering a `<Button>` from `@lenso/ui` somewhere visible to confirm styles are applied.

When done, summarize the changes you made and tell me how to start the dev server.

Install HeroUI and required dependencies:

npm i @lenso/tokens @lenso/ui

Import Styles

Add to your main CSS file globals.css:

@import "tailwindcss";@import "@lenso/tokens"; /* [!code highlight]*/

Import order matters. Always import tailwindcss first.

Use Components

import { Button } from '@lenso/ui';
function App() {  return (    <Button>      My Button    </Button>  );}

What's Next?