Skip to main content

Prerequisites

Setup required before using @osdk/react-components.

Install dependencies​

Tip: If your tooling already installs dependencies, skip this step.

Use whichever package manager your project uses:

# npm
npm install @osdk/api @osdk/client @osdk/react
npm install @osdk/react-components
npm install react react-dom classnames

# pnpm
pnpm add @osdk/api @osdk/client @osdk/react
pnpm add @osdk/react-components
pnpm add react react-dom classnames

# yarn
yarn add @osdk/api @osdk/client @osdk/react
yarn add @osdk/react-components
yarn add react react-dom classnames

Configure the OSDK client​

Create an OSDK client and wrap your app with OsdkProvider:

import { createClient } from "@osdk/client";
import { OsdkProvider } from "@osdk/react";

const client = createClient(
  "https://your-stack.palantirfoundry.com",
  "ri.ontology.main.ontology.{UUID}",
  async () => {
    // return your auth token
  },
);

function App() {
  return <OsdkProvider client={client}>{/* your app */}</OsdkProvider>;
}

All component packages require an OsdkProvider wrapping your app. Without it, data fetching hooks will throw.

CSS setup​

IMPORTANT: Portal isolation (required)​

Components use Base UI portals, which require stacking context isolation:

.root {
  isolation: isolate;
}

Apply this to your root element. See the Base UI docs for details.

Layers​

Import the component styles into a CSS @layer in your application's entry CSS file (e.g., index.css). Using a layer keeps the cascade predictable: later layers always win when styles conflict, regardless of selector specificity, so your own styles and theme overrides take precedence over the defaults.

The examples below import the styles into a layer named osdk.components; declare any of your own layers after it to override.

Without Tailwind​

/* index.css */
@layer osdk.components;

@import "@osdk/react-components/styles.css" layer(osdk.components);

With Tailwind CSS v4​

/* index.css */
@layer tailwind, osdk.components;

@import "tailwindcss" layer(tailwind);

@import "@osdk/react-components/styles.css" layer(osdk.components);

Custom theme overrides​

Add a custom layer after the OSDK layers to override any token:

@layer osdk.components, user.brand;

@import "@osdk/react-components/styles.css" layer(osdk.components);
@import "./user-brand.css" layer(user.brand);

Token scopes​

All components resolve their visual properties through CSS custom properties. There are two scopes of tokens you can target when theming:

  • OSDK tokens (--osdk-*) — every visual property used inside OSDK components resolves through a token prefixed with --osdk- (e.g. --osdk-table-header-bg, --osdk-form-section-padding). Override these to theme OSDK components only, leaving other Blueprint components in your app untouched.
  • Blueprint tokens (--bp-*) — the underlying Blueprint design tokens that most --osdk-* tokens map to. Override these for consistent theming across both Blueprint and OSDK components. (A few --osdk-* tokens hold raw values rather than mapping to a --bp-* token — override those --osdk-* tokens directly.)

Per-component references list the --osdk-* variables each component exposes — see, for example, ObjectTable › Theming. The full catalog of variables lives in CSSVariables.md.

Light and dark mode​

OSDK components ship a built-in dark theme. Wrap your app in <OsdkThemeProvider> to activate it and to let users override the OS preference at runtime:

import { OsdkThemeProvider } from "@osdk/react-components/experimental/theme";

function App() {
  return (
    <OsdkProvider client={client}>
      <OsdkThemeProvider>
        {/* defaults to "system" */}
        {/* your app */}
      </OsdkThemeProvider>
    </OsdkProvider>
  );
}

By default the provider follows prefers-color-scheme and writes the resolved value to data-bp-color-scheme on <html> — matching Blueprint's convention so the theme also applies to portaled overlays (popovers, dialogs, tooltips).

See OsdkThemeProvider for the full reference, including the defaultTheme modes, the useOsdkTheme hook, persisting the user's choice, and integrating with an external theme store via controlled mode.

Accessibility​

When overriding theme tokens, keep the result accessible:

  • Color contrast (WCAG AA): 4.5:1 for normal text, 3:1 for large text.
  • Distinct interactive states: rest, hover, active, selected, and focused should each be visually distinguishable — the default --osdk-table-row-bg-* and --osdk-table-row-border-color-* tokens are designed to meet WCAG AA; preserve that intent in custom themes.