react-ui

@openuidev/react-ui

React components and chat layouts for OpenUI. Use the ready-made chat surfaces, the built-in model-renderable component library, or the individual UI primitives in your own layout.

Links: Package docs | Chat docs | GitHub repo

Install

npm install @openuidev/react-ui @openuidev/react-lang @openuidev/react-headless
# or
pnpm add @openuidev/react-ui @openuidev/react-lang @openuidev/react-headless

Peer dependencies: react >=19.0.0, react-dom >=19.0.0, zustand ^4.5.5, @openuidev/react-lang, @openuidev/react-headless

Don't forget to import the component styles:

import "@openuidev/react-ui/styles/index.css";

Overview

This package provides three layers:

1. Chat layouts for full-screen chat, copilots, and bottom-tray experiences.
2. Model-renderable components for charts, tables, forms, cards, and other OpenUI Lang output.
3. Standalone UI primitives such as Button, Card, Table, Charts, and the chat shell pieces.

Quick Start

The fastest way to get a working chat app:

import { FullScreen } from "@openuidev/react-ui";
import "@openuidev/react-ui/styles/index.css";

function App() {
  return <FullScreen apiUrl="/api/chat" threadApiUrl="/api/threads" />;
}

Chat Layouts

Component	Description
FullScreen	Full-page chat with a thread sidebar
Copilot	Side-panel copilot overlay
BottomTray	Collapsible bottom tray chat

All chat layouts accept apiUrl, threadApiUrl, and theming props. See the chat docs for full configuration.

Copilot example

import { Copilot } from "@openuidev/react-ui";

function App() {
  return (
    <div>
      <main>Your app content</main>
      <Copilot apiUrl="/api/chat" threadApiUrl="/api/threads" />
    </div>
  );
}

Built-in Component Libraries

The package ships with two preconfigured OpenUI Lang libraries:

Export	Description
openuiLibrary	Full component library for charts, tables, forms, cards, images, and more
openuiChatLibrary	Chat-optimized subset with follow-ups, steps, and callouts

Use them directly when building custom chat experiences:

import { Renderer } from "@openuidev/react-lang";
import { openuiLibrary } from "@openuidev/react-ui";

function AssistantMessage({ content, isStreaming }) {
  return <Renderer response={content} library={openuiLibrary} isStreaming={isStreaming} />;
}

Generate a system prompt from the library:

import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui";

const systemPrompt = openuiLibrary.prompt(openuiPromptOptions);

Theming

Wrap your app in ThemeProvider to customize colors, typography, spacing, and effects:

import { ThemeProvider, createTheme } from "@openuidev/react-ui";

const customTheme = createTheme({
  primary: "#6366f1",
  background: "#fafafa",
  foreground: "#1a1a1a",
});

function App() {
  return (
    <ThemeProvider mode="light" lightTheme={customTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

Export	Description
ThemeProvider	Context provider for theming
createTheme(overrides)	Create a theme with validation and defaults
defaultLightTheme	Built-in light theme
defaultDarkTheme	Built-in dark theme
swatchTokens	Token palette for use in theme builders

Styling integration

OpenUI ships its component styles in two variants:

Import	Cascade behavior
@openuidev/react-ui/styles/index.css (default)	Unlayered — override via normal CSS specificity, as in 0.11.x and earlier
@openuidev/react-ui/layered/styles/index.css (opt-in)	Wrapped in @layer openui — any unlayered consumer CSS wins

Need a single component's CSS? Import it per component: ./styles/<Component>.css (unlayered) or ./layered/styles/<Component>.css (layered).

With the layered variant, plain CSS overrides OpenUI without !important or specificity matching:

@import "@openuidev/react-ui/layered/styles/index.css";

/* Wins, no specificity tricks needed */
.openui-button-base-primary {
  background: hotpink;
}

With Tailwind v4 (layered variant)

Declare layer order at the top of your entry stylesheet so openui sits above Tailwind's reset but below components and utilities:

@layer theme, base, openui, components, utilities;
@import "tailwindcss";
@import "@openuidev/react-ui/layered/styles/index.css";

This places Tailwind's Preflight (in base) below OpenUI components so its element resets don't override them, while keeping utilities (bg-red-500, etc.) winning over OpenUI styles.

Rules for the layered variant

• Import OpenUI CSS from exactly one place — multiple import sites under chunk-splitting bundlers (e.g. Turbopack) can register openui before your layer-order statement and lock the wrong order.
• Wrap app-wide resets in a layer below openui (e.g. @layer base { * { margin: 0; } }) — unlayered resets beat all layered styles regardless of specificity.
• ./defaults.css and the ThemeProvider runtime style injection stay unlayered in both modes so runtime theming always overrides component defaults.

Browser support

The layered variant requires CSS cascade layers: Chrome 99+, Firefox 97+, Safari 15.4+, Edge 99+ (all baseline from March 2022). On older browsers the @layer { ... } block is dropped entirely and components render unstyled. The default unlayered styles have no such floor.

Components

All components are available as individual imports:

Category	Components
Layout	Card, CardHeader, SectionBlock, Tabs, Accordion, Carousel, Separator, Steps
Data Display	Table, Charts (bar, line, area, pie, radar, scatter), ListBlock, ListItem, Tag, TagBlock, CodeBlock, Image, ImageBlock, ImageGallery
Forms	Input, TextArea, Select, CheckBoxGroup, CheckBoxItem, RadioGroup, RadioItem, SwitchGroup, SwitchItem, Slider, DatePicker, FormControl, Label
Actions	Button, Buttons, IconButton, FollowUpBlock, FollowUpItem
Feedback	Callout, TextCallout, MessageLoading
Content	TextContent, MarkDownRenderer
Chat	FullScreen, Copilot, BottomTray, Shell.*, CopilotShell.*, ToolCall, ToolResult

Per-component imports

For smaller bundles, import components individually:

import { Button } from "@openuidev/react-ui/Button";
import { Card } from "@openuidev/react-ui/Card";
import { Charts } from "@openuidev/react-ui/Charts";

Subpath Exports

Import path	Description
@openuidev/react-ui	All components and libraries
@openuidev/react-ui/styles/index.css	Full compiled stylesheet, unlayered (default import)
@openuidev/react-ui/layered/styles/index.css	Full stylesheet wrapped in @layer openui (opt-in)
@openuidev/react-ui/defaults.css	Theme tokens, always unlayered
@openuidev/react-ui/genui-lib	OpenUI Lang libraries and prompt options
@openuidev/react-ui/styles/*	Per-component compiled styles (unlayered)
@openuidev/react-ui/layered/styles/*	Per-component styles wrapped in @layer openui
@openuidev/react-ui/scssUtils	SCSS utility functions
@openuidev/react-ui/<Component>	Per-component entry points

Documentation

• React UI API reference
• Chat guides
• Source on GitHub

License

MIT