Customize the React SDK

DatairaInsights is a clean default, not a fixed product shell. Customize it at three levels: feature modes, design tokens, or component composition.

Configure the workspace

<DatairaInsights
  features={{
    navigation: ["dashboards", "metrics", "conversations"],
    search: "global",
    evidence: ["steps"],
    messageActions: ["copy", "retry"],
    resultActions: ["save", "download"],
    controls: "icon-and-label",
    libraryControls: "icon",
    libraryView: "list",
    libraryViewToggle: "visible",
    activity: "auto",
    timezone: "visible",
  }}
  table={{ controls: "auto", sorting: "enabled", pageSize: 20 }}
/>

Arrays control both visibility and order. Use navigation: [] for chat only, or evidence: ["steps"] to keep the useful execution trace without showing SQL or query-result rows.

Match the host theme

Use controlled theme state when users should be able to switch appearance. The SDK renders the control in its own workspace bar, while the host owns persistence.

import { useState } from "react";
import { DatairaInsights, type DatairaTheme } from "@dataira/react";

const [theme, setTheme] = useState<DatairaTheme>("light");

<DatairaInsights theme={theme} onThemeChange={setTheme} />

Pass theme without onThemeChange to lock the SDK to one appearance.

The SDK inherits the host font and exposes CSS variables:

.my-product .dataira-root {
  --dataira-bg: var(--background);
  --dataira-bg-subtle: var(--muted);
  --dataira-fg: var(--foreground);
  --dataira-muted: var(--muted-foreground);
  --dataira-border: var(--border);
  --dataira-accent: var(--primary);
  --dataira-accent-fg: var(--primary-foreground);
  --dataira-radius: var(--radius);
}

className, style, and message overrides let you localize or brand the surface without forking it.

Compose only what you need

Exported hooks include useChat, useMetrics, useDashboards, useDashboard, useCollections, useCollectionItems, and useResourcePreferences. Components include ChatPanel, DataTable, MetricLibrary, DashboardLibrary, WorkspaceSearch, and DatairaDashboard. ResultVisualization is the shared result primitive used by chat, saved-metric previews, and dashboard widgets; its compact density changes layout density without introducing a second table or chart renderer.

Library components support card/list views, controlled or default view state, optional search, inline metric-title editing, pins, and custom children. The metric Add metric to… menu groups dashboard and collection destinations in one floating layer, so opening it does not move or clip content. List previews remain open while the pointer is over the floating result.

Selecting a metric highlights it and supplies its ID/version as page context to the agent. The same removable context chip appears in full and sidebar composers; the workspace assistant control opens the rail while preserving the catalog. The rail's Open conversation action expands the current thread. Headless shells can reproduce this with MetricLibrary.onSelect, useChat page context, and a shared chat controller. Selection is the card highlight; the composer shows the short Context chip instead of duplicating an assistant-context badge. Keep loading skeletons until catalog or message hydration finishes rather than briefly rendering an empty workspace.

Use ChatPanel surface="sidebar" for contextual work and surface="full" for the complete conversation. Mount both against the same useChat result instead of creating two controllers. The sidebar automatically uses compact charts and icon controls while retaining accessible names; the full surface keeps labels and room for long evidence.

Saving and pinning are separate contracts. saveMessage() creates a saved metric and persists the assistant message ID, allowing the Saved state to rehydrate in either surface. useResourcePreferences pins an existing metric, dashboard, collection, or conversation to the top of its library; it never creates a metric.

Result tables attach governed units to measure columns. Saved metric cards keep the original question directly under the title. Their outer metadata row keeps chart type and datasource on the left and lifecycle plus calculation help on the right; the semantic unit remains beside the title. Certified uses a green check plus text, while draft stays neutral. The question-mark action opens an accessible provenance modal, partner tags remain below the question, and library actions stay in a stable footer.

Lifecycle is governed server state, not a tag. Agents and deterministic checks may prepare certification evidence, but only the authorized review workflow can grant certified; saved or discovered metrics otherwise remain draft.

For data answers, the agent returns a concise, corrected metricTitle in the same language as the user's request. useChat().saveMessage(index) stores that title and keeps the original user question in questionText. The optional resolveMetricTitle hook option can enforce a host naming convention without changing the agent prompt.

Use the headless client when your UI should not use any Dataira components.