Open Props UI Documentation

The project is organized as a monorepo consisting of two primary parts:

The Library (packages/opui)

This is the framework-agnostic core, managed as the opui-css workspace package. It contains:

• components/: Folders containing component logic, templates (e.g., Button.astro), and types.
• css/: Component styles, themes, and entry-point imports.
• astro/: The public entry point and barrel exports for Astro projects.

The Documentation Site (src/)

The Astro-based documentation site, containing layouts, pages, and site components.

Open Props UI uses CSS Cascade Layers (@layer) to manage specificity. The defined layer order is:

@layer openprops, theme, normalize, components.root, components.extended, utils;

To override library styles, wrap your custom CSS in a layer that appears after utils in the order above, or use unlayered styles.

To use Open Props UI, install the opui-css package along with open-props using pnpm:

pnpm add opui-css open-props

Peer Dependencies

Depending on your chosen integration method, you may need the following peer dependencies:

• astro ^6 (required only for Astro components)
• vue ^3 (required only for Vue components)
• open-props ^1

To develop on the project or view the documentation site locally, use pnpm to install dependencies and start the development server.

pnpm install
pnpm dev

If you are using Astro, you can import pre-built components directly from opui-css/astro. You must also import the base CSS imports to ensure styles are applied.

---
import "opui-css/css/imports.css"
import { Button, Card } from "opui-css/astro"
---

<Card>
  <Button variant="primary">Click me</Button>
</Card>

Version 5 introduces a ui- prefix to all OPUI-owned CSS classes.

• Framework Components: If you use the provided framework components (e.g., <Button />), no action is required as they automatically emit the prefixed classes.
• Raw HTML/CSS: If you use raw HTML or write custom CSS targeting library classes, you must update your references to include the ui- prefix.
• CSS Variables: All CSS custom properties (e.g., --primary, --surface-default, --size-3) remain unchanged.

Refer to the CHANGELOG.md for the full list of renamed tokens.

<!-- Before v5 -->
<button class="button outlined small">Save</button>

<!-- After v5 -->
<button class="ui-button ui-outlined ui-small">Save</button>

/* Before v5 */
.button.filled { /* override */ }

/* After v5 */
.ui-button.ui-filled { /* override */ }

To add a new component to the opui-css package, follow these steps:

1. Create a new directory for the component in packages/opui/components/[ComponentName].
2. Create the component template file [ComponentName].astro within that folder.
3. Export the new component from the barrel file located at packages/opui/astro/index.ts.
4. (Optional) Add the component-specific styles in packages/opui/css/components/.

If you are unable to migrate to v4 or v5 immediately, you can pin your project to the last stable v3 release. Note that v3 will not receive further updates.

{
  "dependencies": {
    "opui-css": "3.3.5"
  }
}

In version 5.1.0, the critical prop has been renamed to error for all form components.

Affected components:

• TextField
• Checkbox
• Radio
• Switch
• Select
• ClassicSelect
• Textarea

Note: Components used for severity styling (such as Button, Callout, and Badge) still use the critical prop and do not require changes.

<!-- Before v5.1 -->
<TextField critical label="Name" />

<!-- After v5.1 -->
<TextField error label="Name" />

For projects without a build step, you can use a pre-bundled stylesheet via CDN. Use the documented class names (e.g., ui-button, ui-primary) to style elements.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/opui-css/dist/opui.css"
/>

<button class="ui-button ui-primary">Click me</button>

Bundler Optimization

If you use a bundler that resolves CSS @imports (like Vite, Astro, or webpack), import the source files instead of the pre-bundled dist file to enable tree-shaking and only ship the CSS you actually use.

/* Import everything */
@import "opui-css/css/imports.css";

/* Or pick components à la carte */
@import "opui-css/css/components/button.css";

Open Props UI is a CSS UI library designed to explore next-gen HTML and CSS features for component creation. For detailed installation and usage instructions, refer to the official getting started guide.

https://open-props-ui.netlify.app/html/guide/getting-started/