@stackra/ui

Client-side UI kit for the Stackra framework. Re-exports HeroUI OSS and HeroUI Pro components, adds custom composites (ConfirmDialog, FocusModal, FileUpload, PhoneInput, PinLock, PatternLock, …), React hooks, providers, contexts, and every heroicon variant plus an Iconify wrapper that bundles the Gravity UI icon set.

Install

pnpm add @stackra/ui @heroui/react @heroicons/react react react-dom tailwindcss

Optional peers

# HeroUI Pro components (Stepper, Command, Sheet, DataGrid, …)
pnpm add @heroui-pro/react

# Iconify + Gravity UI icons
pnpm add @iconify/react

pnpm approvals for HeroUI Pro

@heroui-pro/react runs a postinstall script that downloads licensed CDN artifacts. pnpm 10+ blocks postinstall by default — allowlist it in your workspace:

# pnpm-workspace.yaml
onlyBuiltDependencies:
  - "@heroui-pro/react"
  - heroui-pro

Then authenticate:

# Step 1 — one-time OAuth login. Opens a browser. Credentials land
# in the OS keyring, user-scoped — covers every fresh workspace
# clone from this machine.
npx heroui-pro@latest login

# Step 2 — hydrate the stubs. MUST run from `packages/frontend/ui/`
# (this package), NOT the monorepo root. The `heroui-pro` CLI looks
# for the packages in the flat `./node_modules/@heroui-pro/react`
# layout. At the monorepo root pnpm hoists everything to
# `./node_modules/.pnpm/`, so the CLI reports "Cannot find in
# node_modules" and exits without downloading. Inside this UI
# package, pnpm creates the flat symlink the CLI expects.
cd packages/frontend/ui
pnpm dlx heroui-pro@latest install

# CI (non-interactive) — set the env var instead of Step 1, then
# run Step 2 identically.
export STACKRA_HEROUI_AUTH_TOKEN=…

Verifying the install succeeded

The stub-only layout is ~4 KB and contains ONLY dist/postinstall/. The hydrated dist is ~4.5 MB and adds dist/components/, dist/libs/, dist/utils/, dist/css/, dist/heroui-pro.min.css. If the postinstall never authenticated, downstream builds fail with:

Error: Could not resolve "@heroui-pro/react" imported by "@stackra/ui"

Fix a stuck stub by re-firing the install from THIS package's directory:

npx heroui-pro@latest login                              # if not already
rm -rf ~/Library/Caches/heroui-pro                       # macOS cache path
cd packages/frontend/ui && pnpm dlx heroui-pro@latest install

pnpm rebuild @heroui-pro/react heroui-native-pro does NOT work as an alternative — the postinstall it fires still runs against pnpm's hoisted layout at the monorepo root and silently no-ops. Always run pnpm dlx heroui-pro@latest install from inside packages/frontend/ui/.

Version pin — do NOT bump past 1.0.0-beta.6

@heroui-pro/[email protected] is a major API redesign — top-level exports (EmptyState, cn, tv, VariantProps) moved to subpath exports, and the barrel index no longer covers the utility layer @stackra/ui depends on. @stackra/ui is authored against beta.6; bumping the catalog breaks the build immediately.

Both @heroui-pro/react and heroui-native-pro stay pinned to 1.0.0-beta.6 in pnpm-workspace.yaml until an ADR reconciles beta.7's breaking changes.

Usage

// HeroUI components + custom composites
import { Button, Card, ConfirmDialog, PhoneInput } from '@stackra/ui/react';

// Platform-agnostic hooks (also work in React Native later)
import { useDebounce } from '@stackra/ui';

// Heroicons — one subpath per glyph size / weight (tree-shaken per import)
import { ArrowLeftIcon } from '@stackra/ui/icons/heroicon/outline'; // 24px stroke
import { CheckIcon }      from '@stackra/ui/icons/heroicon/solid';   // 24px fill
import { XMarkIcon }      from '@stackra/ui/icons/heroicon/mini';    // 20px
import { CogIcon }        from '@stackra/ui/icons/heroicon/micro';   // 16px

// Iconify — universal icon renderer with Gravity UI as default set
import { Iconify } from '@stackra/ui/icons/iconify';

<Iconify icon="star" width={20} />              // Gravity UI (bundled)
<Iconify icon="logos:github-icon" width={20} /> // Remote set via Iconify CDN

// Global CSS
import '@stackra/ui/react/styles';

Custom composites (13)

Every component is composable, accessible, and Tailwind-styled.

| Component | Purpose | | ------------------- | -------------------------------------------------------------------- | | ConfirmDialog | Confirmation modal with configurable variant (danger, warning, info) | | FocusModal | Full-screen focus mode modal for immersive editing flows | | FileUpload | Drag-drop file input with preview grid | | InlineTip | Inline callout (info / warning / danger / success) | | JsonViewSection | Syntax-highlighted, collapsible JSON viewer | | MoneyAmountCell | Locale-aware currency cell for tables | | PatternLock | Android-style connect-the-dots unlock pattern | | PhoneInput | International phone-number input with country picker | | PinLock | PIN entry with masked digits | | ProgressAccordion | Accordion where each section has a status (pending / active / done) | | ProgressTabs | Wizard-style tabs with per-step status (needs @heroui-pro/react) | | SectionContainer | Titled section container for settings pages | | StatusBadge | Colored badge with dot indicator |

Hooks

| Hook | Purpose | | ------------------ | ------------------------------------------- | | useDebounce | Debounce any value with configurable delay | | useConfirmDialog | Imperative API for ConfirmDialog | | useCopyClipboard | Copy to clipboard with success feedback | | usePageProgress | Access the global page-load progress state | | useProgressTabs | Programmatically drive ProgressTabs state |

Providers + contexts

| Provider | Purpose | | ---------------------- | ------------------------------------ | | PageProgressProvider | Global route-load progress bar state |

Both page-progress and progress-tabs also export dedicated React contexts for advanced consumers.

Subpath map

| Import | Purpose | | ------------------------------------ | ----------------------------------------------------------------- | | @stackra/ui | Platform-agnostic hooks (useDebounce) | | @stackra/ui/react | HeroUI OSS + Pro + custom composites + web-only hooks + providers | | @stackra/ui/icons/heroicon/outline | 24px outline heroicons | | @stackra/ui/icons/heroicon/solid | 24px solid heroicons | | @stackra/ui/icons/heroicon/mini | 20px heroicons | | @stackra/ui/icons/heroicon/micro | 16px heroicons | | @stackra/ui/icons/iconify | <Iconify /> component + Gravity UI (bundled) | | @stackra/ui/icons/gravity-ui | Raw Iconify JSON for the Gravity UI set (tooling) | | @stackra/ui/react/styles | Global CSS (HeroUI Pro base + controllers + RTL) |

Styles

Import once at the app entry:

/* app/globals.css */
@import "tailwindcss";
@import "@heroui/styles";
@import "@heroui-pro/react/css"; /* only if using Pro */
@import "@stackra/ui/react/styles";

@stackra/ui/react/styles bundles:

• @heroui-pro/react/css (if Pro is installed)
• Custom pointer / cursor conventions
• Right-to-left (Arabic/Hebrew) layout support

License

MIT