Installation

Get Gui set up, step by step

Gui is easy to set up as we’ve invested into “0-config” installs for all bundlers. That said, it’s easy to get lost if you start configuring too many things too early.

Use npm create hanzogui@latest to pick one of our starter templates.

Requirements

React Native 0.81+ with New Architecture enabled (for native apps)
React 19+
TypeScript 5+ (required)

Gui 2 takes advantage of new style features in React Native 0.81+ including boxShadow, filter, and more. On web, there are no version restrictions.

Installation

To install from scratch:

yarn
npm
bun
pnpm
yarn add @hanzogui/core

Core is just the style library. If you plan to use our full UI kit, you can avoid installing @hanzogui/core and instead:

yarn
npm
bun
pnpm
yarn add hanzogui

The hanzogui package is a superset of core, so anywhere the docs reference @hanzogui/core, you can replace it with hanzogui.

This applies to web-only apps. If you’re building a native or universal app, you already have react-native installed. For web-only apps, you still need react-native types in the parent project for proper prop typing and autocomplete. You can either install react-native directly:

yarn
npm
bun
pnpm
yarn add react-native

Or, if you only want the types:

yarn
npm
bun
pnpm
yarn add [email protected] @types/react-native

Gui’s web runtime is self-contained. In a monorepo, install either option in the parent app or workspace root rather than a leaf package.

Next, you’ll want to set up your configuration and provide it with GuiProvider:

App.tsx
import { GuiProvider, View } from '@hanzogui/core'
import config from './hanzogui.config' // your configuration

export default function App() {
  return (
    <GuiProvider config={config} defaultTheme="light">
      <View width={200} height={200} backgroundColor="$background" />
    </GuiProvider>
  )
}

We have a recommended preset configuration called @hanzogui/config:

yarn
npm
bun
pnpm
yarn add @hanzogui/config

You can use it like so:

App.tsx
import { GuiProvider, createGui } from '@hanzogui/core'
import { defaultConfig } from '@hanzogui/config/v5'

// you usually export this from a hanzogui.config.ts file
const config = createGui(defaultConfig)

type Conf = typeof config

// make imports typed
declare module '@hanzogui/core' {
  interface GuiCustomConfig extends Conf {}
}

export default () => {
  return (
    <GuiProvider config={config} defaultTheme="light">
      {/* your app here */}
    </GuiProvider>
  )
}

Set your root theme using the defaultTheme prop on GuiProvider rather than wrapping your app with <Theme>. This ensures the fastSchemeChange setting works on native, and allows light/dark changes on web to use faster media query-based updates during SSR.

And that’s it!

import { Button } from '@hanzo/gui'

export default function Demo() {
  return <Button theme="blue">Hello world</Button>
}

From here, we recommend spending some time understanding configuration.

100% of Gui features work at both runtime and compile-time, which makes it both easy to use and fast. Because it works fully at runtime, and because we’ve invested a lot into building it such that it doesn’t need any special bundler configuration to work on either native or web, you can begin using Gui with just the above setup.

Next Steps

Once you have Gui installed, you’ll want to explore:

CLI - Command-line tools for building, optimizing, and managing your Gui projects
Bundler Setup - Integration guides for Next.js, Expo, Vite, Webpack, Metro, and more
Design Systems - Build your own optimized component library with Gui

Later on, you can set up the compiler to gain more performance and some nice development helpers.

Bundler Guides

Gui generally doesn’t require any special bundler setup as we’ve worked hard to make it “just work” without configuration in a wide variety of environments.

That said, the broader React Native and React Native Web ecosystem is filled with packages that do need configuration. Gui provides a variety of bundler plugins that help with that:

Next.js

Full-featured React framework with great developer experience.

Expo

Platform for creating universal native apps with JavaScript and React.

Vite

Fast and modern development server and build tool.

Metro

Fast, scalable, and serverless JavaScript bundler for React Native.

One

Universal React framework with native support.

Introduction

Design system

Edit this page on GitHub.