React NativeNative primitives

Lumen for React Native

Use Lumen foundations and native primitives in React Native without depending on CSS, DOM behavior, or the web runtime.

Package@santi020k/lumen-react-native

Install Lumen with its required react-native-svg and datetime-picker peers, then mount one LumenProvider near the application root. The deprecated root date exports keep the datetime picker required for the pre-v2 stability releases; Lumen 2 makes it optional for consumers that use no /datetime imports.

Get started

Install and configure

Before you begin

What you need

Node.js 22.12 or newer for consumer applications
Node.js 22.19 or newer and pnpm for the Lumen repository playground
React 19.2 and React Native 0.86.2 or newer
Expo Go, Xcode, or Android Studio for a native runtime

Install the native package
Run the install command from an existing Expo or React Native application. React and React Native remain peer dependencies supplied by your app; react-native-svg is installed alongside Lumen.
Add the theme provider
Mount one LumenProvider near the application root. Use scheme="system" to follow the device appearance automatically.
Run a native target
Start Expo or your native bundler, then open the app on web, an emulator, a simulator, or a physical device.

pnpm add @santi020k/lumen-react-native react-native-svg @react-native-community/datetimepicker

npm install @santi020k/lumen-react-native react-native-svg @react-native-community/datetimepicker

# Required until Lumen 2 removes the deprecated root date exports
pnpm add @react-native-community/datetimepicker

import {
  LumenButton,
  LumenProvider,
  LumenSurface,
  LumenText
} from '@santi020k/lumen-react-native'

export function App() {
  return (
    <LumenProvider scheme="system">
      <LumenSurface>
        <LumenText variant="title">Welcome</LumenText>
        <LumenButton onPress={() => {}}>Continue</LumenButton>
      </LumenSurface>
    </LumenProvider>
  )
}

# Expo
npx expo start

# React Native Community CLI
npx react-native start

Try every component

Run the React Native playground

Use the browser preview for the quickest public tour. Clone the repository for Expo, simulators, emulators, or physical-device validation; the local path avoids advertising an Expo Go QR code that the current public client cannot open.

pnpm playground:react-native:web

git clone https://github.com/santi020k/lumen.git
cd lumen
pnpm install
pnpm playground:react-native

pnpm --filter @santi020k/lumen-playground-react-native run build:android:apk

Installing locally versus publishing

You can run the gallery locally before configuring any store account.

Run the pinned EAS CLI login and init commands once before the first remote Expo build.
The preview EAS profile produces an installable Android APK.
Production Android and iOS builds require store credentials and signing configured in EAS.

Appearance

Choose and change the theme

LumenProvider follows the device appearance by default. Pass light or dark when an in-app preference should override the system, and keep the provider near the application root so every screen receives the same semantic colors and foundation values.

<LumenProvider scheme="system">
  <AppNavigation />
</LumenProvider>

type Appearance = 'light' | 'dark'

const [appearance, setAppearance] = useState<Appearance>('light')

return (
  <LumenProvider scheme={appearance}>
    <AppNavigation />
  </LumenProvider>
)

Style with semantic roles

Components consume semantic roles such as canvas, surface, ink, brand, success, warning, and danger. Keep product code on those roles rather than assigning one-off colors to individual components.

Verify both appearances

Switch the device between light and dark while the app is open.
Check text and icon contrast in default, disabled, error, and loading states.
Test the largest supported font scale and screen-reader labels in both schemes.

Continue with AI

Give your coding tool the Lumen workflow

Install the portable skill once, open your application in a compatible coding tool, and name the target platform in the request. The skill reads the native package and documentation before selecting components.

1 · Install the skill

npx skills add santi020k/lumen --skill lumen-ui

npx skills add santi020k/lumen --skill lumen-ui

Follow the installer prompts and select the AI coding tools available on your machine.

2 · Ask for the native target

Use $lumen-ui to build this screen in the existing React Native app.
Use @santi020k/lumen-react-native and mount one LumenProvider at the app root.
Preserve navigation and state, and include loading, empty, error, and native accessibility behavior.

Use $lumen-ui to build this screen in the existing React Native app.
Use @santi020k/lumen-react-native and mount one LumenProvider at the app root.
Preserve navigation and state, and include loading, empty, error, and native accessibility behavior.

Review the generated package imports, component states, and platform accessibility behavior.

The Agent Skill and optional MCP server cover web and native adapters. MCP can list the components available for this platform and return installation, setup, API examples, accessibility guidance, and reference source for each documented native component.

Open the complete AI setup guide

Interactive component gallery

Try Lumen on React Native

Explore the React Native components and their interactive states directly in the browser.

View verified React Native runtime capture

Lumen component gallery running in a native React Native Android application

Supported surface

Components and capabilities

These primitives share semantic intent with Web, SwiftUI, and Compose while retaining React Native props, refs, and accessibility behavior.

Sparkline

Line chart

Bar chart

Pie chart

Scatter chart

Heatmap

Range chart

Combo chart

Theme

Text

Surface

Icon

Icon button

Button

Text field

Badge

Divider

Spinner

Card

Alert

Progress

Skeleton

Disclosure

Avatar

Textarea

Field group

Chip

Button group

Toast

Toggle

Settings row

Picker

Slider

Search field

Phone input

Checkbox

Radio group

Segmented control

Tabs

Navigation bar

Empty state

Error state

List row

Banner

Stat

Gauge

Section header

Status bar

Collapsible navigation bar

Navigation accessory

Refresh control

Date field

Date range field

Graphic

Backdrop

Illustration

Image

Alert dialog

Sheet

Share button

Open the full component reference

Platform contract

Designed for React Native

Native foundations

Numeric dimensions and hexadecimal colors are generated directly from the canonical token source.

Native semantics

Components use native accessibility roles, states, touch targets, and refs without a DOM runtime.

Theme context

The provider follows the system color scheme or an explicit light or dark selection.

Move between platform guidance without losing the shared Lumen design language.