## 1. Project Overview & Quickstart (radix-ui/primitives)

## File: README.md

[](https://radix-ui.com/primitives)

# Radix Primitives

**An open-source UI component library for building high-quality, accessible design systems and web apps.**

Radix Primitives is a low-level UI component library with a focus on accessibility, customization and developer experience. You can use these components either as the base layer of your design system, or adopt them incrementally.

---

## Installation

First, install pnpm if you haven't already. Open your terminal and run:

```bash
npm install pnpm
```

Then, install the dependencies:

```bash
pnpm install
```

## Documentation

For full documentation, visit [radix-ui.com/primitives/docs](https://www.radix-ui.com/primitives/docs).

## Releases

For changelog, visit [radix-ui.com/primitives/docs/overview/releases](https://www.radix-ui.com/primitives/docs/overview/releases).

## Contributing

Please follow our [contributing guidelines](./.github/CONTRIBUTING.md).

---

## Community

- [Discord](https://discord.com/invite/7Xb99uG) - To get involved with the Radix community, ask questions and share tips.
- [Twitter](https://twitter.com/radix_ui) - To receive updates, announcements, blog posts, and general Radix tips.

## Thanks

[](https://www.chromatic.com/)

Thanks to [Chromatic](https://www.chromatic.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions.

---

## License

Licensed under the MIT License, Copyright © 2022-present [WorkOS](https://workos.com).

---

## File: apps/ssr-testing/README.md

# `@repo/ssr-testing`

This is a testing playground for SSR support in our primitives using a [Next.js](https://nextjs.org/) project.

## Getting Started

From the root of the repo, run the development server:

```sh
pnpm dev:ssr
```

---

## File: packages/react/visually-hidden/README.md

# `react-visually-hidden`

View docs [here](https://radix-ui.com/primitives/docs/utilities/visually-hidden).

---

## File: packages/react/use-previous/README.md

# `react-use-previous`

This is an internal utility, not intended for public usage.

---

## File: packages/react/use-layout-effect/README.md

# `react-use-layout-effect`

This is an internal utility, not intended for public usage.

---

## File: packages/react/use-is-hydrated/README.md

# `react-use-is-hydrated`

## Usage

This is an internal utility, not intended for public usage.

---

## File: packages/react/use-escape-keydown/README.md

# `react-use-escape-keydown`

This is an internal utility, not intended for public usage.

---

## File: packages/react/use-effect-event/README.md

# `react-use-is-hydrated`

## Usage

This is an internal utility, not intended for public usage.

## 2. Official Technical Reference & Guides (radix-ui/website)

## File: README.md

<a href="https://radix-ui.com" >
  
</a>

# Radix UI website and documentation

**Everything you need to build a design system, website or web app.**

Components, colors, icons, templates, and an extensive design system. Free and open-source.

---

## Documentation

For full documentation, visit [radix-ui.com](https://radix-ui.com).

## Contributing

This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).

Please follow our [contributing guidelines](./.github/CONTRIBUTING.md).

## Getting Started

Run the development server:

```bash
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

## Authors

- Pedro Duarte ([@peduarte](https://twitter.com/peduarte))
- Benoit Grelard ([@benoitgrelard](https://twitter.com/benoitgrelard)) - [WorkOS](https://workos.com)
- Jenna Smith ([@jjenzz](https://twitter.com/jjenzz))
- Colm Tuite ([@colmtuite](https://twitter.com/colmtuite)) - [WorkOS](https://workos.com)
- Chance Strickland ([@chancethedev](https://twitter.com/chancethedev))

---

Copyright © 2022-present [WorkOS](https://workos.com).

---

## File: data/themes/docs/theme/breakpoints.mdx

---
metaTitle: Breakpoints
metaDescription: Built-in breakpoints allow you to easily build
  adapative layouts.
---

# Breakpoints

<Description>
	Built-in breakpoints allow you to easily build adaptive layouts.
</Description>

## Available sizes

Each breakpoint matches a fixed screen width. Values are `min-width` based and apply when the screen width is equal or greater.



## Usage

Most component size and layout props will accept an additional `Responsive` object shape for modifying the given prop across breakpoints.

Each size maps to a corresponding key, the value of each will be applied when the screen size is greater than or equal to the named breakpoint.

```jsx
<Heading
	size={{
		initial: "3",
		md: "5",
		xl: "7",
	}}
/>
```

---

## File: data/themes/docs/theme/color.mdx

---
metaTitle: Color
metaDescription: Understanding the color system and it’s application in your theme.
---

# Color

<Description>
	Understanding the color system and its application in your theme.
</Description>

Radix Themes comes with a number of color scales, each with their own light, dark and alpha variants. Under the hood, the color system is powered by [Radix Colors](/colors).

## Accents

Accent color is the most dominant color in your theme. It is used for primary buttons, links and other interactive elements. `accentColor` is specified directly on the [Theme](/themes/docs/components/theme) component:

```jsx

	<MyApp />

```

#### Available accent colors

There is a range of accent colors to choose from:


	


#### Accent scale anatomy

Each accent is a 12-step scale that includes a solid and a transparent variant of each color. For example, here’s the `indigo` color scale:


	


#### Accent scale tokens

Accent color tokens can be accessed using CSS variables. You can use these tokens to style your custom components, ensuring they are accessible and consistent with the rest of your theme.

```css
/* Backgrounds */
var(--accent-1);
var(--accent-2);

/* Interactive components */
var(--accent-3);
var(--accent-4);
var(--accent-5);

/* Borders and separators */
var(--accent-6);
var(--accent-7);
var(--accent-8);

/* Solid colors */
var(--accent-9);
var(--accent-10);

/* Accessible text */
var(--accent-11);
var(--accent-12);

/* Functional colors */
var(--accent-surface);
var(--accent-indicator);
var(--accent-track);
var(--accent-contrast);
```

---

## Grays

You can also choose between a pure gray or a number of tinted grays. Your accent color will be automatically paired with a gray shade that complements it. However, you can also specify a custom `grayColor` directly on the [Theme](/themes/docs/components/theme) component:

```jsx

	<MyApp />

```

#### Available gray colors

There is 6 grays to choose from. The difference may seem subtle, but it is impactful especially on pages with a lot of text or in dense UIs.


	


#### Gray scale anatomy

Grays are based on the same 12-step color scale that includes a solid and a transparent variant of each color. For example, here’s the `slate` color scale:


	


#### Gray scale tokens

Gray color tokens can be accessed using CSS variables. You can use these tokens to style your custom components, ensuring they are accessible and consistent with the rest of your theme.

```css
/* Backgrounds */
var(--gray-1);
var(--gray-2);

/* Interactive components */
var(--gray-3);
var(--gray-4);
var(--gray-5);

/* Borders and separators */
var(--gray-6);
var(--gray-7);
var(--gray-8);

/* Solid colors */
var(--gray-9);
var(--gray-10);

/* Accessible text */
var(--gray-11);
var(--gray-12);

/* Functional colors */
var(--gray-surface);
var(--gray-indicator);
var(--gray-track);
var(--gray-contrast);
```

---

## Color overrides

When available, the `color` prop on the components can be used to override the theme accent.
Nested components will automatically inherit the new accent color.

```jsx live=true line=17

	<Flex align="start" direction={{ initial: "column", sm: "row" }} gap="4">
		<Callout.Root>
			<Callout.Icon>
				
			</Callout.Icon>
			<Callout.Text>
				<Flex as="span" align="center" gap="4">
					<Text>There are new commits.</Text>
					
						Refresh
					
				</Flex>
			</Callout.Text>
		</Callout.Root>

		<Callout.Root color="gray">
			<Callout.Icon>
				
			</Callout.Icon>
			<Callout.Text>
				<Flex as="span" align="center" gap="4">
					<Text>There are new commits.</Text>
					
						Refresh
					
				</Flex>
			</Callout.Text>
		</Callout.Root>
	</Flex>

```

#### Individual color tokens

Individual colors can be accessed directly using similar CSS variables by their corresponding names. For example, the reds are accessed via `--red-1`, `--red-2`, and so on up to `--red-12`.

---

## High contrast

Most of the time, components with a `color` prop also provide a `highContrast` option that achieves appearance that stands out against the page background:

```jsx live=true line="5"
<Flex gap="4">
	
		Edit profile
	
	
		Edit profile
	
</Flex>
```

---

## Focus and selection

Radix Themes automatically adjusts the focus and selection colors depending on the accent color of the current component. Most of the time, setting the `color` prop will intelligently change the focus and selection colors to avoid a mismatch of conflicting hues:

```jsx live=true line="1,6,9"

	<Flex direction="column" gap="4">
		<Text>
			Complete your account setup in <Link href="#">settings</Link>
		</Text>
		<Text color="gray">
			Complete your account setup in <Link href="#">settings</Link>
		</Text>
		<Text color="red">
			Complete your account setup in <Link href="#">settings</Link>
		</Text>
	</Flex>

```

#### Focus scale tokens

Focus color tokens can be accessed using CSS variables that follow a similar naming structure like the other scales, e.g. `--focus-1`, `--focus-2`, and so on up to `--focus-12`.

Most of the components use `--focus-8` for the focus outline color.

---

## Alpha colors

Every color has an alpha variant which is designed to appear visually the same when placed over the page background. This is a powerful tool that allows colors to look naturally when overlayed over another background. All numerical color steps have a corresponding alpha variant.

```css
/* Solid colors */
var(--red-1);
var(--red-2);
...
var(--red-12);

/* Alpha colors */
var(--red-a1);
var(--red-a2);
...
var(--red-a12);
```

Alpha colors are used automatically within Radix Themes components—no additional configuration is required.

---

## Backgrounds

A number of background colors are used to create a sense of visual hierarchy in Radix Themes UIs. These colors are used for backgrounds, cards, and other surfaces.

```css
/* Page background */
var(--color-background);

/* Panel backgrounds, such as cards, tables, popovers, dropdown menus, etc. */
var(--color-panel-solid);
var(--color-panel-translucent);

/* Form component backgrounds, such as text fields, checkboxes, select, etc. */
var(--color-surface);

/* Dialog overlays */
var(--color-overlay);
```

### Panel background

The `panelBackground` prop controls whether panelled elements use a solid or a translucent background color. The default `translucent` value creates a subtle overlay effect:

```jsx

	<MyApp />

```


	


While `solid` is useful when you'd prefer to present information unobstructed.

```jsx

	<MyApp />

```


	


---

## Customization

Radix Themes colors can be customized by overriding the corresponding CSS variables of the token system. Refer to the [source code](https://github.com/radix-ui/themes/blob/main/packages/radix-ui-themes/src/styles/tokens/color.css) for the full list of the color tokens.

Make sure that your CSS is applied after the Radix Themes styles so that it takes precedence.

### Brand color

You can replace a specific color with your brand color by remapping the corresponding token. Usually, you’d override **step 9** of the scale that you are using as your theme accent.

```css
.radix-themes {
	--my-brand-color: #3052f6;
	--indigo-9: var(--my-brand-color);
	--indigo-a9: var(--my-brand-color);
}
```

In this example, using solid-colored `indigo` components will now reference your custom color.

### Custom palette

You can use the [custom color palette tool](/colors/custom) to generate a custom palette based just on a couple reference colors. Once you are happy with the result, paste the generated CSS into your project. You can rename the generated colors to match the accent that you want to use in your theme.

To generate dark theme colors, toggle the appearance to use the dark theme. Make sure to paste the generated CSS after your light theme color overrides.

<Text as="div" align="center" my="6">
	
		<Link asChild>
			<NextLink href="/colors/custom">
				
			</NextLink>
		</Link>
	
	{[Create a custom palette →](/colors/custom)}
</Text>

### Color aliasing

You may prefer to use generic color names to refer to the color shades that you want to use. For example, it is common to refer to `crimson`, `jade`, and `indigo` as `red`, `green`, and `blue` respectively.

In this case, you can remap Radix Themes tokens in place of one another and reclaim the color names you want to use:

```css
.radix-themes {
	--red-1: var(--ruby-1);
	--red-2: var(--ruby-2);
	--red-3: var(--ruby-3);
	--red-4: var(--ruby-4);
	--red-5: var(--ruby-5);
	--red-6: var(--ruby-6);
	--red-7: var(--ruby-7);
	--red-8: var(--ruby-8);
	--red-9: var(--ruby-9);
	--red-10: var(--ruby-10);
	--red-11: var(--ruby-11);
	--red-12: var(--ruby-12);

	--red-a1: var(--ruby-a1);
	--red-a2: var(--ruby-a2);
	--red-a3: var(--ruby-a3);
	--red-a4: var(--ruby-a4);
	--red-a5: var(--ruby-a5);
	--red-a6: var(--ruby-a6);
	--red-a7: var(--ruby-a7);
	--red-a8: var(--ruby-a8);
	--red-a9: var(--ruby-a9);
	--red-a10: var(--ruby-a10);
	--red-a11: var(--ruby-a11);
	--red-a12: var(--ruby-a12);

	--red-surface: var(--ruby-surface);
	--red-indicator: var(--ruby-indicator);
	--red-track: var(--ruby-track);
	--red-contrast: var(--ruby-contrast);
}
```

In this example, using the `red` color in Radix Themes components and tokens would now reference the original `ruby` scale.

---

## Individual CSS files

Color definitions comprise around 20% of the total CSS size that Radix Themes ships with.

If you’d prefer to reduce your CSS bundle size and have access just to the colors you use, you can import the individual CSS files for each color module. Here’s a sample setup:

```ts
// Base theme tokens
import "@radix-ui/themes/tokens/base.css";

// Include just the colors you use, for example `ruby`, `teal`, and `slate`.
// Remember to import the gray tint that matches your theme setting.
import "@radix-ui/themes/tokens/colors/ruby.css";
import "@radix-ui/themes/tokens/colors/teal.css";
import "@radix-ui/themes/tokens/colors/slate.css";

// Rest of the CSS
import "@radix-ui/themes/components.css";
import "@radix-ui/themes/utilities.css";
```

Please note that the colors you didn’t import will still be accepted by the `color` prop in React. Also, make sure that your developer tooling [preserves](/themes/docs/overview/styling#nextjs-import-order) the order of the imported CSS files.

---

## File: data/themes/docs/theme/cursors.mdx

---
metaTitle: Cursors
metaDescription: Customizing cursors used for interactive elements.
---

# Cursors

<Description>Customizing cursors used for interactive elements.</Description>

## Default cursors

By default, interactive elements that don’t link to another page use the regular arrow cursor. This also matches the browser defaults. However, disabled elements use an explicit disabled cursor.

```jsx live="true"
<Flex align="center" gap="4" wrap="wrap">
	<Flex align="center" gap="3" wrap="wrap">
		Button
		
			[Link](#)
		
		Disabled
	</Flex>
	Ghost button
	<Link href="#" size="2">
		Link
	</Link>
	<Checkbox defaultChecked />
	<Switch defaultChecked />
	<Switch defaultChecked disabled />
</Flex>
```

## Cursor tokens

Cursor settings can be accessed using CSS variables. You can use these tokens to style your custom components, ensuring they are accessible and consistent with the rest of your theme.

```css
/* Available cursor tokens */
var(--cursor-button);
var(--cursor-checkbox);
var(--cursor-disabled);
var(--cursor-link);
var(--cursor-menu-item);
var(--cursor-radio);
var(--cursor-slider-thumb);
var(--cursor-slider-thumb-active);
var(--cursor-switch);
```

## Customization

It’s common to use a pointer cursor for interactive elements. Radix Themes cursors can be customized by overriding the corresponding CSS variables of the token system.

Here’s an example of how you can customize the cursor tokens to set `cursor: pointer` for most interactive elements in the theme:

```css
.radix-themes {
	--cursor-button: pointer;
	--cursor-checkbox: pointer;
	--cursor-disabled: default;
	--cursor-link: pointer;
	--cursor-menu-item: pointer;
	--cursor-radio: pointer;
	--cursor-slider-thumb: grab;
	--cursor-slider-thumb-active: grabbing;
	--cursor-switch: pointer;
}
```

Make sure that your CSS is applied after the Radix Themes styles so that it takes precedence.

---

## File: data/themes/docs/theme/dark-mode.mdx

---
metaTitle: Dark mode
metaDescription: Using appearance to manage and integrate dark mode.
---

# Dark mode

<Description>Using appearance to manage and integrate dark mode.</Description>

## Overview

Light and dark modes are supported out of the box, allowing you to easily switch appearance without additional design or styling.


	


## Basic usage

By default, the root `Theme` appearance is `light`. To set a different appearance pass it via the `appearance` prop. This will force the theme to use the specified setting.

```jsx line=1

	<MyApp />

```

## Inheriting system appearance

A common requirement is to inherit the appearance setting from a user’s system preferences.

This is a deceptively complex problem to solve given SSR, SSG and client side hydration considerations. To make implementation easier, we recommend integrating with a theme switching library.

### With next-themes

Integration with `next-themes` is simple and straightforward because Radix Themes implements matching class names.

To enable dark mode, use `` from `next-themes` with `attribute="class"`.

```jsx line=6
import { Theme } from "@radix-ui/themes";
import { ThemeProvider } from "next-themes";

export default function () {
	return (
		
			
				<MyApp />
			
		
	);
}
```

{

<Callout.Root my="5" color="gray">
	<Callout.Icon>
		
	</Callout.Icon>
	<Callout.Text>
		**Do not** try to set{" "}
		`{""}`. Instead, rely just on
		class switching that `next-themes` provides. This way{" "}
		`next-themes` can prevent the appearance flash during initial
		render.
	</Callout.Text>
</Callout.Root>

}

### With other libraries

Any library that supports class switching is compatible. You’ll just need to ensure that the appended class names match those supported by Radix Themes:

- `className="light"`
- `className="light-theme"`
- `className="dark"`
- `className="dark-theme"`

---

## File: data/themes/docs/theme/overview.mdx

---
metaTitle: Theme overview
metaDescription: Use the Theme component to change the look and feel of your UI.
---

# Theme overview

<Description>
	Use the Theme component to change the look and feel of your UI.
</Description>

## Anatomy

The [Theme component](/themes/docs/components/theme) defines the overall visual look of your application. It can be customized by passing a minimal set of configuration options.

```jsx live=true

	

```

A well tuned set of defaults is provided to get you started, but don’t be afraid to play with all of the available options to find the right visual style for your application. Check out the [Playground](/themes/playground) to see what effect each option has.

## Variants

Variants are visual variations of a component which are used to create visual hierarchies and communicate relative importance.

Each component offers a different set of variants, though all are designed to be consistent and complimentary with each other.

```jsx live=true
<Flex gap="3" align="center">
	
		Get started <ArrowRightIcon />
	
	
		Get started <ArrowRightIcon />
	
	
		Get started <ArrowRightIcon />
	
</Flex>
```

## Examples

Using a combination of component variants alongside customized theme settings allows you to create a multitude of unique-looking interfaces.

For example you could create:

- [Music applications](/themes/example-music-app)
- [Ecommerce product elements](/themes/example-ecommerce)
- [SaaS dashboards](/themes/example-dashboard)

Or any number of differing treatments and styles.



## Tokens

Tokens provide direct access to theme values and give you flexibility to build and customize your own themed components.

For all available theme tokens see the [source code](https://github.com/radix-ui/themes/tree/main/packages/radix-ui-themes/src/styles/tokens), or read more about each type of token in the relevant theme pages.

{

  <Grid columns={{ initial: '1', xs: '2' }} my="6" gap="4">
      

      

      

      

      

      

    </Grid>

}

---

## File: data/themes/docs/theme/radius.mdx

---
metaTitle: Radius
metaDescription: Choosing the right radius setting in your theme.
---

# Radius

<Description>Choosing the right radius setting in your theme.</Description>

## Theme setting

Theme `radius` setting manages the radius factor applied to the components:

```jsx line="1"

	<TextField.Root size="3" placeholder="Reply…">
		<TextField.Slot side="right" px="1">
			Send
		</TextField.Slot>
	</TextField.Root>

```


	


The resulting `border-radius` is contextual and differs depending on the component. For example, when set to `full`, a [Button](/themes/docs/components/button) becomes pill-shaped, while a [Checkbox](/themes/docs/components/checkbox) will never become fully rounded to prevent any confusion between it and a [Radio](/themes/docs/components/radio).

```jsx live=true

	<Flex align="center" gap="3">
		Save
		<Switch defaultChecked />
		<Checkbox defaultChecked />
	</Flex>

```

## Radius overrides

Certain components allow you to override the radius factor using their own `radius` prop.

```jsx live=true
<Flex align="center" gap="3">
	Save
	Save
	Save
	Save
	Save
</Flex>
```

Components that render panels, like Card, Dialog, and Popover, among others, won’t have the `radius` prop, but will inherit the radius setting from the theme. The `radius` prop is also unavailable on most text-based components.

## Radius scale

Radius values used in the components are derived from a 6-step scale.


	


While you can’t use a specific step on a particular component directly—the `radius` prop is used to set just the radius factor—you can use the radius scale to style your own components.

Radius tokens are accessed using CSS variables. You can use these tokens to style your custom components, ensuring they are consistent with the rest of your theme.

```css
/* Radius values that automatically respond to the radius factor */
var(--radius-1);
var(--radius-2);
var(--radius-3);
var(--radius-4);
var(--radius-5);
var(--radius-6);

/* A multiplier that controls the theme radius */
var(--radius-factor);

/*
 * A variable used to calculate a fully rounded radius.
 * Usually used within a CSS `max()` function.
 */
var(--radius-full);

/*
 * A variable used to calculate radius of a thumb element.
 * Usually used within a CSS `max()` function.
 */
var(--radius-thumb);
```

---

## File: data/themes/docs/theme/shadows.mdx

---
metaTitle: Shadows
metaDescription: Understanding the shadow styles used in your theme.
---

# Shadows

<Description>Understanding the shadow styles used in your theme.</Description>

Shadows used in the components are derived from a 6-step scale. Refer to the [source code](https://github.com/radix-ui/themes/blob/main/packages/radix-ui-themes/src/styles/tokens/shadow.css) for the actual values used to achieve these shadows.


	


#### Shadow tokens

Shadow tokens can be accessed using CSS variables. You can use these tokens to style your custom components, ensuring they are consistent with the rest of your theme.

```css
/* Inset shadow */
var(--shadow-1);

/* Shadows for variant="classic" panels, like Card */
var(--shadow-2);
var(--shadow-3);

/* Shadows for smaller overlay panels, like Hover Card and Popover */
var(--shadow-4);
var(--shadow-5);

/* Shadows for larger overlay panels, like Dialog */
var(--shadow-6);
```

---

## File: data/themes/docs/theme/spacing.mdx

---
metaTitle: Spacing
metaDescription: Overview of the space scale and scaling options.
---

# Spacing

<Description>Overview of the space scale and scaling options.</Description>

## Space scale

Spacing values are derived from a 9-step scale, which is used for props such as margin and padding. These props accept numeric strings from `"1"` to `"9"`, which correspond to the steps in the scale below.


	




#### Space scale tokens

Space scale tokens can be also accessed using CSS variables. You can use these tokens to style your custom components, ensuring they are consistent with the rest of your theme.

```css
/* Space scale */
var(--space-1);
var(--space-2);
var(--space-3);
var(--space-4);
var(--space-5);
var(--space-6);
var(--space-7);
var(--space-8);
var(--space-9);
```

## Scaling

Values which affect layout (spacing, font size, line height) scale relatively to each other based on the `scaling` value defined in your Theme. This setting allows you to scale the UI density uniformly across your entire application.

```jsx line="1"

	<Card variant="surface">
		<Flex gap="3" align="center">
			<Avatar size="3" src={person.image} fallback={person.name} />
			
				<Text as="div" size="2" weight="bold">
					{person.name}
				</Text>
				<Text as="div" size="2" color="gray">
					Approved invoice <Link>#3461</Link>
				</Text>
			
		</Flex>
	</Card>

```


	


#### Scaling factor

The scaling factor token can be accessed using the `--scaling` CSS variable. If you need to use different scaling factors in your app, you can use this token in your custom styles, ensuring they are consistent with the rest of your theme.

```css
.MyCustomComponent {
	width: calc(200px * var(--scaling));
}
```