Upgrading from v1 to v2

Update Dependencies

Bump all @hanzogui/* and @hanzo/gui packages to ^2.0.0:

# if using npm/yarn/pnpm, update all gui packages
npx hanzo-gui check

Removed packages

• @hanzogui/animations-moti -- use @hanzogui/animations-reanimated (same API)
• @hanzogui/image-next -- use Image from @hanzo/gui directly

Add resolutions

In monorepos, you may want to add resolutions to avoid duplicate copies of core packages (critical for context/provider to work):

"resolutions": {
  "@hanzogui/core": "^2.0.0",
  "@hanzogui/web": "^2.0.0",
  "@hanzo/gui": "^2.0.0"
}

Config Migration (v4 to v5)

You don't have to migrate to Config v5, and it changes some default style behaviors that may cause some issues. It's easier to migrate to Hanzo GUI 2 first, then Config v5 after if you do choose to. Config v5 is mostly a superset of v5, but some media query names changed and some themes and colors are different.

Update imports

// before
import { defaultConfig } from '@hanzogui/config/v4'

// after
import { defaultConfig } from '@hanzogui/config/v5'
import { animations } from '@hanzogui/config/v5-css' // animations are now separate

Animations are no longer bundled with the config. Choose your driver:

• @hanzogui/config/v5-css -- CSS transitions (smallest bundle, web-only)
• @hanzogui/config/v5-rn -- React Native Animated API
• @hanzogui/config/v5-reanimated -- Reanimated (best native performance)
• @hanzogui/config/v5-motion -- Motion (Web Animations API, experimental)

Add animations to config

import { defaultConfig } from '@hanzogui/config/v5'
import { animations } from '@hanzogui/config/v5-css'
import { createGui } from '@hanzo/gui'

export const config = createGui({
  ...defaultConfig,
  animations,
})

export type Conf = typeof config

declare module '@hanzo/gui' {
  interface GuiCustomConfig extends Conf {}
}

Settings changes

All root-level createGui settings have moved into the settings object:

// before (v1)
createGui({
  defaultFont: 'body',
  disableRootThemeClass: true,
  // ...
})

// after (v2)
createGui({
  ...defaultConfig,
  settings: {
    ...defaultConfig.settings,
    // your overrides
  },
})

Removed settings:

• maxDarkLightNesting -- removed entirely
• cssStyleSeparator -- removed entirely
• themeClassNameOnRoot -- handled by addThemeClassName
• disableRootThemeClass -- now part of settings

Flex and position defaults

v5 changes two important defaults:

• flexBasis changes from auto to 0 (React Native standard)
• position changes from relative to static (browser default)

If your layout relies on the old behavior, restore it:

settings: {
  ...defaultConfig.settings,
  styleCompat: 'legacy',         // restores flexBasis: auto
  defaultPosition: 'relative',   // restores position: relative
}

Otherwise, you may need to add position="relative" explicitly on containers that have absolutely-positioned children, and add flexBasis="auto" where needed.

Media query renames

• $2xl → $xxl
• $2xs → $xxs
• $max2Xl → $max-xxl
• $maxXl → $max-xl
• $maxLg → $max-lg
• $maxMd → $max-md
• $maxSm → $max-sm

Max queries changed from camelCase to kebab-case. New height-based queries are also available ($height-sm, $height-md, etc.) and a $pointerTouch query.

Breakpoint values now match Tailwind CSS: 640, 768, 1024, 1280, 1536.

Colors and themes

Colors have been updated to Radix Colors v3 with slightly different values. Legacy colors are available at @hanzogui/colors/legacy.

v5 adds new color themes: orange, pink, purple, teal, gray, neutral.

// before (v1) - manual theme-builder
import { createThemes, defaultComponentThemes } from '@hanzogui/theme-builder'
const themes = createThemes({ ... })

// after (v2) - simplified
import { createV5Theme, defaultChildrenThemes } from '@hanzogui/themes/v5'
const themes = createV5Theme({
  childrenThemes: {
    ...defaultChildrenThemes,
    // add custom color themes
    cyan: { light: cyan, dark: cyanDark },
  },
})

Component themes are off by default in v5. Use defaultProps in your config instead:

createGui({
  ...defaultConfig,
  defaultProps: {
    Button: { theme: 'accent' },
  },
})

Theme tree-shaking (SSR optimization)

On the client, you can skip loading theme JS and hydrate from CSS variables instead:

themes: process.env.VITE_ENVIRONMENT === 'client'
  ? ({} as typeof themes)
  : themes,

Prop Renames

These are the most common find-and-replace changes.

animation to transition

// before
<View animation="bouncy" />
<Sheet.Overlay animation="lazy" />

// after
<View transition="bouncy" />
<Sheet.Overlay transition="lazy" />

The TypeScript type also changed: AnimationProp to TransitionProp.

tag to render

// before
<View tag="nav" />
<View tag="button" />

// after
<View render="nav" />
<View render="button" />

For tag="a", consider using the Anchor component instead.

Stack to View

// before
import { Stack, type StackProps } from '@hanzo/gui'

// after
import { View, type ViewProps } from '@hanzo/gui'

themeInverse / <Theme inverse> to theme="accent"

// before
<Button themeInverse>Primary</Button>
<Theme inverse><Card>...</Card></Theme>

// after
<Button theme="accent">Primary</Button>
<Theme name="accent"><Card>...</Card></Theme>

space / spaceDirection to gap

// before
<YStack space="$4" spaceDirection="both">

// after
<YStack gap="$4">

onHoverIn / onHoverOut

// before
<View onHoverIn={handler} onHoverOut={handler} />

// after
<View onPointerEnter={handler} onPointerLeave={handler} />

ellipse to numberOfLines

// before
<Text ellipse>Long text...</Text>

// after
<Text numberOfLines={1}>Long text...</Text>

Shadow Migration

Replace React Native shadow props with CSS boxShadow:

// before
<View
  shadowColor="$shadow3"
  shadowRadius={20}
  shadowOffset={{ height: 10, width: 0 }}
/>

// after
<View boxShadow="0 10px 20px $shadow3" />

The format is x y blur color. Multiple shadows are comma-separated. Spread and inset are also supported.

Accessibility Props

All React Native accessibility props are replaced with web-standard ARIA equivalents:

• accessibilityLabel → aria-label
• accessibilityRole → role
• accessibilityHint → aria-describedby
• accessibilityState={{ disabled }} → aria-disabled
• accessibilityState={{ selected }} → aria-selected
• accessibilityState={{ checked }} → aria-checked
• accessibilityState={{ busy }} → aria-busy
• accessibilityState={{ expanded }} → aria-expanded
• accessibilityValue → aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext
• accessibilityElementsHidden → aria-hidden
• accessibilityViewIsModal → aria-modal
• accessibilityLiveRegion → aria-live
• accessible → tabIndex={0}
• focusable → tabIndex
• nativeID → id

Component API Changes

Input

Input now uses web-standard HTML attributes as the primary API:

// before
<Input
  keyboardType="email-address"
  secureTextEntry
  returnKeyType="send"
  textContentType="emailAddress"
  onChangeText={(text) => setText(text)}
  onKeyPress={(e) => {
    if (e.nativeEvent.key === 'Enter') submit()
  }}
  editable={false}
/>

// after
<Input
  inputMode="email"
  type="password"
  enterKeyHint="send"
  autoComplete="email"
  onChange={(e) => setText(e.target?.value ?? e.nativeEvent?.text ?? '')}
  onKeyDown={(e) => {
    if (e.key === 'Enter') submit()
  }}
  readOnly
/>

The old React Native props still work but are deprecated.

Image

Image now uses web-standard src instead of React Native's source:

// before
<Image
  source={{ uri: 'https://example.com/photo.jpg', width: 200, height: 200 }}
  resizeMode="cover"
/>

// after
<Image
  src="https://example.com/photo.jpg"
  width={200}
  height={200}
  objectFit="cover"
/>

Button

• Text style props (fontFamily, fontSize, etc.) removed from the direct API -- style text through child components
• Now defaults to type="button" to prevent accidental form submissions
• useButton hook is deprecated

ListItem

• Text style props removed -- use ListItem.Text and ListItem.Subtitle child components
• Internal spacing props (spaceFlex, scaleSpace) removed

Tabs

• activationMode now defaults to 'manual' (was 'automatic') -- users must click or press Enter to change tabs, matching web standards
• Tabs.Trigger deprecated in favor of Tabs.Tab

Group

• Group.Item wrapper is now required (no more auto-cloning direct children)
• Removed props: space, separator, scrollable, showScrollIndicator, disablePassBorderRadius, forceUseItem
• Add <Separator /> manually between items when needed

Sheet / Popover.Sheet

Popover.Sheet sub-components are replaced with standalone Sheet:

// before
<Adapt when="maxMd" platform="touch">
  <Popover.Sheet modal dismissOnSnapToBottom>
    <Popover.Sheet.Frame p="$4">
      <Adapt.Contents />
    </Popover.Sheet.Frame>
    <Popover.Sheet.Overlay animation="quick" />
  </Popover.Sheet>
</Adapt>

// after
<Adapt when="max-md" platform="touch">
  <Sheet modal dismissOnSnapToBottom>
    <Sheet.Frame p="$4">
      <Adapt.Contents />
    </Sheet.Frame>
    <Sheet.Overlay transition="quick" />
  </Sheet>
</Adapt>

Select

SelectLabel is now SizableText-based instead of ListItem-based.

Removed APIs

• <Spacer /> removed from core -- import from @hanzogui/spacer
• composeEventHandlers -- compose manually: (val) => { a(val); b?.(val) }
• useTheme(props) -- use <Theme> component instead
• ThemeableStack -- use View
• backgrounded prop -- use bg="$background"
• selectable prop -- use select="text"
• animatePresence prop (inline) -- wrap with <AnimatePresence> component
• scrollbarWidth prop -- use CSS
• isWindowDefined -- use isBrowser from @hanzogui/constants
• useTheme from @hanzogui/next-theme -- renamed to useThemeSetting
• @hanzogui/react-native-use-responder-events -- use pointer events (onPointerDown, etc.)

Native Setup

v2 requires explicit setup imports for native features. Add these at the top of your app entry before any Hanzo GUI imports. Note these are optional and mostly new, so only if you were using native gradient, or toast before do you need to do this.

// portals (Sheet, Dialog, Popover, Select, Toast)
import '@hanzogui/native/setup-teleport'

// LinearGradient
import '@hanzogui/native/setup-expo-linear-gradient'

// Toast (burnt)
import '@hanzogui/native/setup-burnt'

// Menu (zeego)
import '@hanzogui/native/setup-zeego'

// for smoother Sheet on native:
import '@hanzogui/native/setup-gesture-handler'

Expo Router entry point

With Expo Router, these setup imports must run before expo-router/entry. Create a custom entry point:

// index.js (at project root)
import '@hanzogui/native/setup-zeego'
// add other setup imports here as needed

import 'expo-router/entry'

Then update your package.json:

{
  "main": "index.js"
}

This ensures native modules like zeego are configured before Expo Router initializes your app.

Build Config

Not much has changed, but there's some nice improvements you can make:

Vite

import { guiAliases, guiPlugin } from '@hanzogui/vite-plugin'

export default {
  plugins: [guiPlugin()],
  resolve: {
    alias: [
      ...guiAliases({
        rnwLite: true, // use lightweight react-native-web
        svg: true,
      }),
    ],
  },
}

Create a gui.build.ts at your project root:

import type { GuiBuildOptions } from '@hanzo/gui'

export default {
  components: ['@hanzo/gui'],
  config: './src/gui.config.ts',
  outputCSS: './src/gui.generated.css',
} satisfies GuiBuildOptions

Metro (Expo / React Native)

No special Metro configuration is needed for Hanzo GUI v2. A standard Expo Metro config works out of the box:

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config')
const config = getDefaultConfig(__dirname)

module.exports = config

Next.js (Turbopack)

Add resolveExtensions and a react-native-safe-area-context shim:

// next.config.js
module.exports = {
  turbopack: {
    resolveAlias: {
      'react-native': 'react-native-web',
      'react-native-svg': '@hanzogui/react-native-svg',
      'react-native-safe-area-context': './shims/react-native-safe-area-context.js',
    },
    resolveExtensions: [
      '.web.tsx',
      '.web.ts',
      '.web.js',
      '.web.jsx',
      '.tsx',
      '.ts',
      '.js',
      '.jsx',
      '.json',
    ],
  },
}

CSS

We recommend generating Hanzo GUI CSS to gui.generated.css, just so it's easier to configure linters and such:

// before
import './gui.css'

// after
import './gui.generated.css'

Generate it with: npx hanzo-gui generate-css --output ./src/gui.generated.css

Quick Reference: Find-and-Replace Patterns

These are the most common replacements you can do across your codebase. Run carefully and review each change:

animation=     ->  transition=
AnimationProp  ->  TransitionProp
AnimationKeys  ->  TransitionKeys
tag=           ->  render=
themeInverse   ->  theme="accent"
<Theme inverse ->  <Theme name="accent"
<Stack         ->  <View
</Stack>       ->  </View>
StackProps     ->  ViewProps
onHoverIn=     ->  onPointerEnter=
onHoverOut=    ->  onPointerLeave=
$2xl=          ->  $xxl=
$2xs=          ->  $xxs=
maxMD          ->  max-md
maxLG          ->  max-lg
maxSM          ->  max-sm
maxXL          ->  max-xl
max2Xl         ->  max-xxl

New Features Worth Knowing

While not required for migration, these v2 features can improve your app:

• boxShadow -- full CSS box-shadow support with tokens
• backgroundImage -- CSS gradients with token support
• filter, mixBlendMode -- graphical effects
• scope prop on Dialog, Popover, Sheet, Tooltip -- mount once at root for performance
• activeStyle / activeTheme on Switch, Checkbox, ToggleGroup, Tabs
• Multiple animation drivers via animatedBy prop
• transition delay and enter/exit control -- transition={{ enter: 'lazy', exit: 'quick' }}
• Menu and ContextMenu -- new components with native platform rendering
• Headless components -- @hanzogui/switch-headless, @hanzogui/checkbox-headless, etc.
• CLI commands -- gui build, gui generate, gui generate-prompt, gui check
• ~32% smaller core bundle (37KB to 25KB gzipped)