April 1, 2026

HeroUI Native v1.0.1 is a patch release focused on reliability and developer experience. It resolves a race condition in the Toast provider that caused stale animation values, corrects disabled-state styling across seven components to use the native disabled: modifier, and introduces a new --backdrop theme variable for overlay components.

Installation

Update to the latest version:

npm i heroui-native

pnpm add heroui-native

yarn add heroui-native

bun add heroui-native

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

Try It on Your Device

Don't have the HeroUI Native app yet? Download it below.

Download on App StoreAndroid · Coming soon

API Enhancements

`--backdrop` Theme Variable

A new --backdrop top-level style variable has been added to the theme system, providing a dedicated color token for the dimming layer behind overlay components such as Dialog and Bottom Sheet. The default value is oklch(0% 0 0 / 20%) for a subtle but visible backdrop effect.

New capability:

import { Dialog } from "heroui-native";

// Dialog and Bottom Sheet overlays now use bg-backdrop automatically
<Dialog>
  <Dialog.Content>
    {/* Content renders over the themed backdrop */}
  </Dialog.Content>
</Dialog>

The --backdrop variable is included in all built-in themes for both light and dark modes, and the corresponding bg-backdrop Tailwind utility is available for use in custom component styles.

Related PR: #366

Style Fixes

Disabled State Modifier

Updated disabled-state styling across seven components to use the disabled: modifier prefix instead of applying styles unconditionally. This ensures disabled styles (opacity-disabled, pointer-events-none) are only applied when the component is in an actual disabled state, respecting the native disabled modifier from Uniwind.

Affected components:

All isDisabled variant classes now use the disabled: modifier prefix (e.g., disabled:opacity-disabled disabled:pointer-events-none), ensuring proper scoping to the disabled pseudo-state and eliminating styling conflicts when the disabled state is toggled dynamically.

Related PR: #361

Bug Fixes

This release includes fixes for the following issues:

Issue #359: Fixed a race condition in the Toast provider where the total SharedValue could drift out of sync with the actual toast count. The manual increment/decrement approach was prone to stale-closure mismatches when hide and show ran in the same tick or when auto-dismiss raced with a manual hide. The total value is now derived from toasts.length via a useEffect, ensuring animated interpolations (opacity, scale, translateY) always reflect the real toast count.
Issue #356: Resolved disabled-state styles being applied unconditionally when isDisabled was true, preventing developers from theming or customizing the disabled appearance. All seven affected components now use the disabled: modifier prefix, correctly scoping styles to the disabled pseudo-state.

Related PRs:

#360
#361

Updated Documentation

The following documentation pages have been updated to reflect the changes in this release:

Colors - Added the new --backdrop variable to the color reference
Theming - Updated theming guide with the new --backdrop variable documentation

Contributors

Thanks to everyone who contributed to this release!

v1.0.1