Getting started

Installation

One package, a handful of peers, and a config plugin for your icons.

Install

Terminal

npx expo install @hzblj/kara-ui \
  @expo/ui \
  @lodev09/react-native-true-sheet \
  expo-image \
  react-native-reanimated \
  react-native-worklets

For the router pieces — Tabs, navigationTheme and ZoomTransition — add Expo Router too:

Terminal

npx expo install expo-router

Peer	Why
`@expo/ui`	The SwiftUI and Jetpack Compose views the native tier renders.
`@lodev09/react-native-true-sheet`	`Sheet` and the sheets built on it.
`expo-image`	`Image`, `Avatar` and the photos in a `ZoomTransition`.
`react-native-reanimated`, `react-native-worklets`	`Pressable`’s spring, `Skeleton`, `Snackbar`.
`expo-router` (optional)	`@hzblj/kara-ui/router`.

Config plugin

The plugin turns a folder of SVGs into native icons at prebuild and writes their names as types. Add it to the app config, then prebuild and build a development client.

app.config.ts

export default {
  plugins: [['@hzblj/kara-ui', {icons: {source: './assets/icons'}}]],
}

Terminal

npx expo prebuild
npx expo run:ios     # or run:android

A new SVG, a change to the plugin’s options or a kara upgrade with native changes all need a prebuild and a native run — not a Metro reload. See Icons.

Provider

KaraProvider goes at the root, once. It carries the theme, the active breakpoint for responsive sx, and the appearance — pinned to light or dark on the platform too, so native and React Native views agree. With Expo Router, hand navigationTheme(theme) to its ThemeProvider so headers and tab bars take the same colours.

app/_layout.tsx

import {KaraProvider, useAppTheme} from '@hzblj/kara-ui'
import {navigationTheme} from '@hzblj/kara-ui/router'
import {Stack, ThemeProvider} from 'expo-router'
import {type ReactNode, useMemo} from 'react'

const Navigation = ({children}: {children: ReactNode}) => {
  const theme = useAppTheme()
  const value = useMemo(() => navigationTheme(theme), [theme])

  return <ThemeProvider value={value}>{children}</ThemeProvider>
}

export default function RootLayout() {
  return (
    <KaraProvider themePreference="system">
      <Navigation>
        <Stack />
      </Navigation>
    </KaraProvider>
  )
}

Entry points

Import	What it holds
`@hzblj/kara-ui`	Every component, the `sx` engine, the theme and the haptics.
`@hzblj/kara-ui/router`	`Tabs`, `navigationTheme`, `ZoomTransition` — everything that needs Expo Router.
`@hzblj/kara-ui/swift-ui`	kara’s raw SwiftUI and UIKit views, for building your own.
`@hzblj/kara-ui/jetpack-compose`	kara’s raw Compose views.