v3.0.0-beta.2

Six new components (AlertDialog, ComboBox, Dropdown, InputGroup, Modal, NumberField), Select API improvements, and component refinements.

November 20, 2025

This release introduces six essential new components, improves the Select component API, and includes various refinements and bug fixes.

Installation

Update to the latest version:

1npm i @lenso/tokens@beta @lenso/ui@beta

Using AI assistants? Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the HeroUI MCP Server.

What's New

New Components

This release introduces 6 new essential components:

AlertDialog: Modal dialog for important decisions that require user confirmation. (Documentation)
ComboBox: Combines a text input with a listbox, allowing users to filter a list of options. (Documentation)
Dropdown: Displays a list of actions or options that a user can choose. (Documentation)
InputGroup: Group related input controls with prefix and suffix elements for enhanced form fields. (Documentation)
Modal: Dialog overlay for focused user interactions and important content. (Documentation)
NumberField: Number input with increment/decrement buttons, validation, and internationalized formatting. (Documentation)

AlertDialog

1"use client";2
3// Adapted from HeroUI v3.2.6 alert-dialog-default (Apache-2.0).4import * as stylex from "@stylexjs/stylex";5import { AlertDialog, Button } from "@lenso/ui";6
7const styles = stylex.create({ popup: { maxWidth: 400 } });8
9export function Default() {10  return (11    <AlertDialog>12      <AlertDialog.Trigger render={<Button variant="danger" />}>Delete Project</AlertDialog.Trigger>13      <AlertDialog.Portal>14        <AlertDialog.Backdrop />15        <AlertDialog.Viewport>16          <AlertDialog.Popup xstyle={styles.popup}>17            <AlertDialog.Close aria-label="Close dialog" />18            <AlertDialog.Header>19              <AlertDialog.Icon variant="danger" />20              <AlertDialog.Title>Delete project permanently?</AlertDialog.Title>21            </AlertDialog.Header>22            <AlertDialog.Body>23              <AlertDialog.Description>24                This will permanently delete <strong>My Awesome Project</strong> and all of its25                data. This action cannot be undone.26              </AlertDialog.Description>27            </AlertDialog.Body>28            <AlertDialog.Footer>29              <AlertDialog.Close render={<Button variant="tertiary" />}>Cancel</AlertDialog.Close>30              <AlertDialog.Close render={<Button variant="danger" />}>31                Delete Project32              </AlertDialog.Close>33            </AlertDialog.Footer>34          </AlertDialog.Popup>35        </AlertDialog.Viewport>36      </AlertDialog.Portal>37    </AlertDialog>38  );39}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

ComboBox

1"use client";2// HeroUI v3.2.6, Apache-2.0. Native Base UI adaptation.3import { AnimalPicker } from "./shared";4export function Default() {5  return <AnimalPicker />;6}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

1"use client";2
3// Adapted from HeroUI v3.2.6 dropdown-default (Apache-2.0).4import { Button, Dropdown } from "@lenso/ui";5import { ActionItem, Popup } from "./_shared";6
7export function Default() {8  return (9    <Dropdown>10      <Dropdown.Trigger render={<Button aria-label="Menu" variant="secondary" />}>11        Actions12      </Dropdown.Trigger>13      <Popup>14        <ActionItem label="New file" onClick={() => console.log("Selected: new-file")} />15        <ActionItem label="Copy link" onClick={() => console.log("Selected: copy-link")} />16        <ActionItem label="Edit file" onClick={() => console.log("Selected: edit-file")} />17        <ActionItem18          label="Delete file"19          variant="danger"20          onClick={() => console.log("Selected: delete-file")}21        />22      </Popup>23    </Dropdown>24  );25}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

1"use client";2
3// Adapted from HeroUI v3.2.6 modal-default (Apache-2.0).4import { Rocket } from "@gravity-ui/icons";5import * as stylex from "@stylexjs/stylex";6import { Button, Modal } from "@lenso/ui";7
8const styles = stylex.create({9  popup: { maxWidth: 360 },10  icon: { backgroundColor: "var(--default)", color: "var(--foreground)" },11  rocket: { width: 20, height: 20 },12  continue: { width: "100%" },13});14
15export function Default() {16  return (17    <Modal>18      <Modal.Trigger render={<Button variant="secondary" />}>Open Modal</Modal.Trigger>19      <Modal.Portal>20        <Modal.Backdrop />21        <Modal.Viewport>22          <Modal.Popup xstyle={styles.popup}>23            <Modal.Close aria-label="Close dialog" />24            <Modal.Header>25              <Modal.Icon xstyle={styles.icon}>26                <Rocket {...stylex.props(styles.rocket)} />27              </Modal.Icon>28              <Modal.Title>Welcome to HeroUI</Modal.Title>29            </Modal.Header>30            <Modal.Body>31              <Modal.Description>32                A beautiful, fast, and modern React UI library for building accessible and33                customizable web applications with ease.34              </Modal.Description>35            </Modal.Body>36            <Modal.Footer>37              <Modal.Close render={<Button xstyle={styles.continue} />}>Continue</Modal.Close>38            </Modal.Footer>39          </Modal.Popup>40        </Modal.Viewport>41      </Modal.Portal>42    </Modal>43  );44}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

InputGroup

1"use client";2// Adapted from HeroUI v3.2.6, Apache-2.0.3import { Globe } from "@gravity-ui/icons";4import { InputGroup, Label, TextField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  field: { width: "100%", maxWidth: 280 },8  icon: { width: 16, height: 16, color: "var(--muted)" },9});10export function WithIconPrefixAndTextSuffix() {11  return (12    <TextField xstyle={styles.field} name="website">13      <Label>Website</Label>14      <InputGroup>15        <InputGroup.Prefix>16          <Globe aria-hidden="true" {...stylex.props(styles.icon)} />17        </InputGroup.Prefix>18        <InputGroup.Input xstyle={styles.field} defaultValue="heroui" />19        <InputGroup.Suffix>.com</InputGroup.Suffix>20      </InputGroup>21    </TextField>22  );23}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

NumberField

1"use client";2
3// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.4import { Label, NumberField, TextField } from "@lenso/ui";5import { Controls, styles } from "./parts";6
7export function Basic() {8  return (9    <TextField name="width" xstyle={styles.field}>10      <NumberField defaultValue={1024} min={0} name="width">11        <Label>Width</Label>12        <Controls />13      </NumberField>14    </TextField>15  );16}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Style Improvements

Custom Variants and Theme Compatibility

Enhanced CSS variants and theme system for better customization:

Motion Preferences:

New motion-safe variant with data-reduce-motion="true" attribute matching
Enhanced motion-reduce now supports ancestor elements and pseudo-elements

Dark Mode:

Class and data-theme="dark" attribute selectors now take precedence over prefers-color-scheme
Full support for pseudo-elements in dark mode

Theme Variables:

Expanded light theme scope to support nested themes (:root, .light, .default, [data-theme="light"], [data-theme="default"])

Component Improvements

Select Component API Update

The Select component's API has been improved for better consistency with other components. The Content subcomponent has been renamed to Popover.

Before:

1<Select>2  <Select.Trigger>3    <Select.Value />4    <Select.Indicator />5  </Select.Trigger>6  <Select.Content>7    <ListBox>8      {/* items */}9    </ListBox>10  </Select.Content>11</Select>

After:

1<Select>2  <Select.Trigger>3    <Select.Value />4    <Select.Indicator />5  </Select.Trigger>6  <Select.Popover>7    <ListBox>8      {/* items */}9    </ListBox>10  </Select.Popover>11</Select>

Chip component sizes have been updated for better consistency:

Small (sm): px-1 py-0 text-xs
Medium (md): text-xs (now explicitly set)
Large (lg): px-3 py-1 text-sm font-medium

Separator Component Enhancement

The Separator component now automatically detects when it's placed inside a surface component (one that uses bg-surface) and applies the appropriate divider color for better visibility. A new isOnSurface prop is also available for manual control.

New Calculated Variable:

--color-separator-on-surface: A calculated variable (automatically generated using color-mix) that ensures the separator is visible when placed on a surface background. Like other calculated variables, it can be overridden in your theme.

Usage:

1<div className="bg-surface">2  <Separator isOnSurface />3</div>

The isOnSurface prop is automatically applied when the Separator detects a SurfaceContext provider (used by components like Card, Alert, Popover, Modal, etc.).

You can also use the calculated variable directly with Tailwind classes:

1<div className="bg-surface">2  <div className="h-px w-full bg-separator-on-surface" />3</div>

Animation Improvements

Loading state spinner color updated for better visibility
Select and Slider component styles adjusted for improved animations
Checkbox animation improved (faster transition)
Better support for prefers-reduced-motion with pseudo elements

⚠️ Breaking Changes

Select Component

The Select.Content subcomponent has been renamed to Select.Popover for consistency with other components like ComboBox and Dropdown.

Migration:

Replace all instances of Select.Content with Select.Popover:

1// Before2<Select.Content>3  <ListBox>...</ListBox>4</Select.Content>5
6// After7<Select.Popover>8  <ListBox>...</ListBox>9</Select.Popover>

Type imports:

1// Before2import type { SelectContentProps } from "@lenso/ui"3
4// After5import type { SelectPopoverProps } from "@lenso/ui"

Named exports:

1// Before2import { SelectContent } from "@lenso/ui"3
4// After5import { SelectPopover } from "@lenso/ui"

CSS Variables and Utilities: Divider → Separator

All CSS variables and utility classes related to divider have been renamed to separator for consistency with the Separator component name.

CSS Variables:

1/* Before */2border-bottom: 1px solid var(--divider);3
4/* After */5border-bottom: 1px solid var(--separator);

Tailwind Utility Classes:

1// Before2<div className="bg-divider" />3<div className="border-divider" />4
5// After6<div className="bg-separator" />7<div className="border-separator" />

Theme Overrides:

If you have custom themes that override the divider variable, update them:

1/* Before */2:root {3  --divider: oklch(92% 0.004 286.32);4}5
6.dark {7  --divider: oklch(22% 0.006 286.033);8}9
10/* After */11:root {12  --separator: oklch(92% 0.004 286.32);13}14
15.dark {16  --separator: oklch(22% 0.006 286.033);17}

Bug Fixes

Fixed loading state spinner color for better visibility
Fixed bordered focus styles taking precedence over hover states
Fixed animation stuttering in documentation
Improved modal form styling
Enhanced motion reduce support for pseudo elements
Fixed mobile hover states sticking after touch interactions by wrapping hover styles in @media (hover: hover) media queries. Also simplified data attribute selectors by removing unnecessary ="true" value checks.

Contributors

Thanks to everyone who contributed to this release!

HeroUI contributors

v3.0.0-beta.2

Installation

What's New

New Components

AlertDialog

ComboBox

Dropdown

Modal

InputGroup

NumberField

Style Improvements

Custom Variants and Theme Compatibility

Component Improvements

Select Component API Update

Chip Component Refinements

Separator Component Enhancement

Animation Improvements

⚠️ Breaking Changes

Select Component

CSS Variables and Utilities: Divider → Separator

Bug Fixes

Links

Contributors