gui/apps/gui.hanzo.ai/data/docs/intro/installation.mdx

---
title: Installation
description: Get Gui set up, step by step
---

<IntroParagraph>
  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.
</IntroParagraph>

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:

```bash
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:

```bash
yarn add hanzogui
```

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

<Notice>
  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:

```bash
yarn add react-native
```

Or, if you only want the types:

```bash
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.

</Notice>

Next, you'll want to set up your [configuration](/docs/core/configuration) and
provide it with `GuiProvider`:

```tsx fileName="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`:

```bash
yarn add @hanzogui/config
```

You can use it like so:

```tsx fileName="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>
  )
}
```

<Notice>
  Set your root theme using the `defaultTheme` prop on `GuiProvider` rather than wrapping your app with `<Theme>`. This ensures the [`fastSchemeChange` setting](/docs/core/configuration#settings) works on native, and allows light/dark changes on web to use faster media query-based updates during SSR.
</Notice>

And that's it!

<Preview>
  <DemoButton />
</Preview>

```tsx class=preview line=5
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](/docs/core/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](/docs/guides/cli)** - Command-line tools for building, optimizing, and
  managing your Gui projects
- **[Bundler Setup](/docs/guides/next-js)** - Integration guides for Next.js,
  Expo, Vite, Webpack, Metro, and more
- **[Design Systems](/docs/guides/design-systems)** - Build your own optimized
  component library with Gui

Later on, you can [set up the compiler](/docs/intro/compiler-install) 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:

<Spacer />

<Grid gap="$4">
  <LogoCard
    title="Next.js"
    img="/logos/next-js.svg"
    link="/docs/guides/next-js"
    subtitle="Full-featured React framework with great developer experience."
    colorOffset={2}
  />
  <LogoCard
    title="Expo"
    img="/logos/expo.svg"
    link="/docs/guides/expo"
    subtitle="Platform for creating universal native apps with JavaScript and React."
    colorOffset={6}
  />
  <LogoCard
    title="Vite"
    img="/logos/vite.svg"
    link="/docs/guides/vite"
    subtitle="Fast and modern development server and build tool."
    colorOffset={1}
  />
  <LogoCard
    title="Metro"
    img="/logos/metro.svg"
    link="/docs/guides/metro"
    subtitle="Fast, scalable, and serverless JavaScript bundler for React Native."
    colorOffset={3}
  />
  <LogoCard
    title="One"
    img="/logos/one.svg"
    link="/docs/guides/one"
    subtitle="Universal React framework with native support."
    colorOffset={4}
  />
</Grid>