Native Integrations

Hanzo GUI components work great out of the box, but several offer optional native integrations for improved performance and platform-native UX. All native integrations are opt-in - components work without them, just with slightly different behavior.

@hanzogui/native Package

The @hanzogui/native package provides setup utilities for native integrations. Import the setup modules at your app's entry point, before any Hanzo GUI imports.

npm install @hanzogui/native

Portal

Native portals preserve React context - the default implementation on native uses a JS-based approach that breaks React context, or requires you to hoist data awkwardly. With native portals, your custom contexts (navigation, app state) work inside Sheet, Dialog, Popover, and other portaled content.

Setup

npm install react-native-teleport

// App.tsx - before any Hanzo GUI imports
import '@hanzogui/native/setup-teleport'

See Portal docs for full details.

Sheet Gestures

Native gesture coordination - makes sheets feel smoother and not get confused with scrollable content during drags. Without this, scroll and pan gestures can occasionally conflict on iOS.

Setup

npm install react-native-gesture-handler

// App.tsx - before any Hanzo GUI imports
import '@hanzogui/native/setup-gesture-handler'
import { GestureHandlerRootView } from 'react-native-gesture-handler'

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>{/* Your app */}</GestureHandlerRootView>
  )
}

See Sheet docs for full details.

Menu & ContextMenu

Native menus - renders platform-native context menus instead of custom overlays. Uses iOS's native menu API for haptics, blur effects, and system integration.

Setup

npm install zeego @react-native-menu/menu react-native-ios-context-menu react-native-ios-utilities sf-symbols-typescript

// App.tsx - before any Hanzo GUI imports
import '@hanzogui/native/setup-zeego'

Then use the native prop:

<Menu native>{/* menu content */}</Menu>

See Menu docs and ContextMenu docs for full details.

Toast

Native toasts - uses platform-native toast implementations:

• iOS: SPIndicator (system-style indicators)
• Android: ToastAndroid
• Web: Notification API

Setup

npm install burnt

// App.tsx - before any Hanzo GUI imports
import '@hanzogui/native/setup-burnt'

Then use the native prop on ToastProvider:

<Toast.Provider native>{/* your app */}</Toast.Provider>

See Toast docs for full details.

LinearGradient

Native gradients - uses expo-linear-gradient for high-performance native gradient rendering.

Setup

npm install expo-linear-gradient

// App.tsx - before any Hanzo GUI imports
import '@hanzogui/native/setup-expo-linear-gradient'

See LinearGradient docs for full details.