From a383feaf6d0ef2c6ab43f726236c6583d9851526 Mon Sep 17 00:00:00 2001 From: wulala0102 Date: Thu, 15 Jan 2026 21:12:39 +0800 Subject: [PATCH 1/3] feat: add llms.txt --- next-env.d.ts | 3 +- package.json | 6 +- pnpm-lock.yaml | 26 +- public/llms-colors.txt | 624 ++ public/llms-full.txt | 17672 +++++++++++++++++++++++++++++++++++ public/llms-primitives.txt | 7482 +++++++++++++++ public/llms-themes.txt | 9550 +++++++++++++++++++ public/llms.txt | 160 + scripts/generate-llms.ts | 296 + 9 files changed, 35812 insertions(+), 7 deletions(-) create mode 100644 public/llms-colors.txt create mode 100644 public/llms-full.txt create mode 100644 public/llms-primitives.txt create mode 100644 public/llms-themes.txt create mode 100644 public/llms.txt create mode 100644 scripts/generate-llms.ts diff --git a/next-env.d.ts b/next-env.d.ts index 725dd6f24..a4a7b3f5c 100644 --- a/next-env.d.ts +++ b/next-env.d.ts @@ -1,6 +1,5 @@ /// /// -/// // NOTE: This file should not be edited -// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information. +// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information. diff --git a/package.json b/package.json index 230af4f44..fce48da11 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,8 @@ }, "scripts": { "dev": "next dev", - "build": "next build", + "build": "pnpm generate:llms && next build", + "generate:llms": "npx tsx scripts/generate-llms.ts", "start": "next start", "prettier": "prettier --write .", "typecheck": "tsc --noEmit", @@ -74,6 +75,9 @@ "husky": "^9.1.6", "prettier": "^3.3.3", "pretty-quick": "^4.0.0", + "remark-mdx": "^3.1.1", + "remark-parse": "^11.0.0", + "remark-stringify": "^11.0.0", "sucrase": "3.29.0", "typescript": "^5.5.4" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 744eca439..58ec5e3ed 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -171,6 +171,15 @@ importers: pretty-quick: specifier: ^4.0.0 version: 4.0.0(prettier@3.3.3) + remark-mdx: + specifier: ^3.1.1 + version: 3.1.1 + remark-parse: + specifier: ^11.0.0 + version: 11.0.0 + remark-stringify: + specifier: ^11.0.0 + version: 11.0.0 sucrase: specifier: 3.29.0 version: 3.29.0 @@ -3494,8 +3503,8 @@ packages: remark-mdx-frontmatter@4.0.0: resolution: {integrity: sha512-PZzAiDGOEfv1Ua7exQ8S5kKxkD8CDaSb4nM+1Mprs6u8dyvQifakh+kCj6NovfGXW+bTvrhjaR3srzjS2qJHKg==} - remark-mdx@3.0.1: - resolution: {integrity: sha512-3Pz3yPQ5Rht2pM5R+0J2MrGoBSrzf+tJG94N+t/ilfdh8YLyyKYtidAYwTveB20BoHAcwIopOUqhcmh2F7hGYA==} + remark-mdx@3.1.1: + resolution: {integrity: sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==} remark-parse@11.0.0: resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==} @@ -3506,6 +3515,9 @@ packages: remark-slug@6.1.0: resolution: {integrity: sha512-oGCxDF9deA8phWvxFuyr3oSJsdyUAxMFbA0mZ7Y1Sas+emILtO+e5WutF9564gDsEN4IXaQXm5pFo6MLH+YmwQ==} + remark-stringify@11.0.0: + resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==} + remote-origin-url@0.4.0: resolution: {integrity: sha512-HYhdsT2pNd0LP4Osb0vtQ1iassxIc3Yk1oze7j8dMJFciMkW8e0rdg9E/mOunqtSVHSzvMfwLDIYzPnEDmpk6Q==} engines: {node: '>= 0.8.0'} @@ -4453,7 +4465,7 @@ snapshots: hast-util-to-jsx-runtime: 2.3.0 markdown-extensions: 2.0.0 periscopic: 3.1.0 - remark-mdx: 3.0.1 + remark-mdx: 3.1.1 remark-parse: 11.0.0 remark-rehype: 11.1.1 source-map: 0.7.4 @@ -8290,7 +8302,7 @@ snapshots: unified: 11.0.5 yaml: 2.5.1 - remark-mdx@3.0.1: + remark-mdx@3.1.1: dependencies: mdast-util-mdx: 3.0.0 micromark-extension-mdxjs: 3.0.0 @@ -8320,6 +8332,12 @@ snapshots: mdast-util-to-string: 1.1.0 unist-util-visit: 2.0.3 + remark-stringify@11.0.0: + dependencies: + '@types/mdast': 4.0.4 + mdast-util-to-markdown: 2.1.0 + unified: 11.0.5 + remote-origin-url@0.4.0: dependencies: parse-git-config: 0.2.0 diff --git a/public/llms-colors.txt b/public/llms-colors.txt new file mode 100644 index 000000000..e216c5e5c --- /dev/null +++ b/public/llms-colors.txt @@ -0,0 +1,624 @@ +# Radix Colors - Complete Documentation + +> Radix Colors is a gorgeous, accessible color system for designing beautiful websites and apps. + +# Overview + +## Aliasing + +How to use Radix Colors. + +# Aliasing + +A guide to providing semantic aliases for colors. + +## Semantic aliases + +Referencing color scales by their actual scale name can work well, like `blue` and `red`. But often, creating semantic aliases like `accent`, `primary`, `neutral`, or `brand` can be helpful, especially when it comes to theming. + +With this approach, you will likely run into issues where you need to use the same scale for multiple semantics. Common examples include: + +- If you map `yellow` to "warning", you might also need `yellow` to communicate "pending". +- If you map `red` to "danger", you might also need `red` to communicate "error" or "rejected". +- If you map `green` to "success", you might also need `green` to communicate "valid". +- If you map `blue` to "accent", you might also need `blue` to communicate "info". + +In this scenario, you can choose to define multiple semantic aliases which map to the same scale. + +Or you can simply recommend that your teammates defer to the original scale name for situations where there is no appropriate semantic alias. + +## Use case aliases + +Each step in Radix Colors scales is designed for a specific use case. To help your team know which step to use, you can provide aliases based on the designed use cases. + +Again, with this approach, you will likely run into issues where you need to use the same step for multiple use cases. Common examples include: + +- Step 9 is designed for solid backgrounds, but it also may work for input placeholder text. +- Step 8 is designed for hovered component borders, but it also works well for focus rings. + +In these cases, you can choose to define multiple aliases which map to the same step. + +Or you can simply recommend that your teammates defer to the original step number for situations where use cases don't have an alias. + +## Mutable aliases + +When designing for both light and dark modes, you sometimes need to map a variable to one color in light mode, and another color in dark mode. Common examples include: + +- Components that have a white background in light mode and a subtle gray background in dark mode. For example, Card, Popover, DropdownMenu, HoverCard, Dialog etc. +- Components that have a transparent black background in light mode and a transparent white background in dark mode. For example, Tooltip. +- Shadows that are saturated, transparent gray in light mode, and pure black in dark mode. +- An overlay that is light transparent black in light mode, and a darker transparent black in dark mode. + +Avoid using specific variable names like "CardBg", or "Tooltip", because you will likely need to use each variable for multiple use cases. + +## Renaming scales + +If you wish, you can rename scales. Reasons might include: + +- Rename a saturated gray to `gray` to keep things simple. +- Rename `sky` or `grass` to `blue` or `green` to keep the naming intuitive. +- Rename a scale to match your brand, like how Discord use `blurple`. + +--- + +## Custom palettes + +How to create custom Radix Colors palettes. + +# Custom palettes + +Learn how to create custom Radix Colors palettes. + +Use the [custom color palette tool](/colors/custom) to generate a Radix Colors scale based just on a couple reference colors. Once you are happy with the result, paste the generated CSS into your project and use them the same way you would use the regular Radix Colors scales. + +The generated scales are based on the Radix Colors scales themselves, so they will work well with similar component designs. As long as you use a reasonable background color, the contrast ratios will be similar to what Radix Colors provide. + +## What you get + +Your custom color palette will include Radix Colors steps 1 through 12, as well as their alpha variants and wide-gamut color definitions. Wide-gamut color definitions are needed to ensure that alpha colors are displayed with full saturation in wide-gamut color spaces, such as on Apple’s displays that support P3. This is because alpha blending works differently in P3 than in sRGB. + +Learn about the base palette composition in the [Understanding the scale](/colors/docs/palette-composition/understanding-the-scale) guide. The generated CSS also includes a few extra colors used exclusively in [Radix Themes](/themes/docs), such as: + +- Surface color, used by certain `variant="surface"` components +- Indicator color, used by components like Checkbox, Radio, and Tabs +- Track color, used by components like Slider and Progress Bar + +Feel free to remove colors from the generated CSS that you don’t need. + +## Color formats + +You can use any common CSS color format in the input fields, or even wide-gamut color spaces, such as `color(display-p3 1 0.5 0)`. The generated CSS will provide the closest sRGB fallbacks. + +## Dark theme + +To generate dark theme colors, toggle the appearance to dark in the website header. Make sure to paste the generated CSS after your light theme color overrides. + +--- + +## Installation + +How to install Radix Colors. + +# Installation + +How to install Radix Colors. + +## npm + +Install Radix Colors from your terminal via npm, yarn or pnpm. Current version is `3.0.0` + +```bash +# with npm +npm install @radix-ui/colors +# with yarn +yarn add @radix-ui/colors +# with pnpm +pnpm add @radix-ui/colors +``` + +## CDN + +To get started quickly, you can use the CDN files. + +```html + + + + + + + + + +``` + +The example above uses the `@latest` tag to point to the latest version of the scales. You can pin your scales to a specific version. + +```html + + +``` + +--- + +## Releases + +Radix Colors changelog. + +# Releases + +Radix Colors releases and changelog. + +## 3.0.0 + + + +- \[**Breaking**] A complete rework of all colors. +- Add P3 colorspace versions of all scales. + +## 2.1.0 + + + +- Add `ruby`, `iris`, and `jade` scales + +## 2.0.1 + + + +- Fix some of the dark `a2` colors being too opaque. + +## 2.0.0 + + + +- \[**Breaking**] A complete rework of all colors, dramatically improving contrast across the board. + +## 1.0.0 + + + +- \[**Breaking**] CSS variables were changed to use the hyphen-separated naming: + - `gray1` → `gray-1` + - `grayA1` → `gray-a1` +- \[**Breaking**] CSS file names were changed to use the hyphen-separated naming: + - `gray.css` → `gray.css` + - `grayA.css` → `gray-alpha.css` + - `grayDark.css` → `gray-dark.css` + - `grayDarkA.css` → `gray-dark-alpha.css` + +## 0.1.9 + + + +- Apply light scale CSS variables to `.light-theme` class in addition to + the `:root` element. + +--- + +## How to use Radix Colors + +How to use Radix Colors. + +# Usage + +How to use Radix Colors with various styling solutions. + +Radix Colors scales are just simple JavaScript objects, so you can use them with your preferred styling solution easily. Below you can find usage examples for popular styling solutions. + +## Vanilla CSS + +Radix Colors provides the colors bundled as raw CSS files. You can import them directly in your files when using a bundler, such as Parcel or Webpack. + +```css +/* Import only the scales you need */ +@import "@radix-ui/colors/gray.css"; +@import "@radix-ui/colors/blue.css"; +@import "@radix-ui/colors/green.css"; +@import "@radix-ui/colors/red.css"; +@import "@radix-ui/colors/gray-dark.css"; +@import "@radix-ui/colors/blue-dark.css"; +@import "@radix-ui/colors/green-dark.css"; +@import "@radix-ui/colors/red-dark.css"; + +/* Use the colors as CSS variables */ +.button { + background-color: var(--blue-4); + color: var(--blue-11); + border-color: var(--blue-7); +} +.button:hover { + background-color: var(--blue-5); + border-color: var(--blue-8); +} +``` + +```html + + + + +``` + +## styled-components + +```js +import { + gray, + blue, + red, + green, + grayDark, + blueDark, + redDark, + greenDark, +} from "@radix-ui/colors"; +import styled, { ThemeProvider } from "styled-components"; + +// Create your theme +const theme = { + colors: { + ...gray, + ...blue, + ...red, + ...green, + }, +}; + +// Create your dark theme +const darkTheme = { + colors: { + ...grayDark, + ...blueDark, + ...redDark, + ...greenDark, + }, +}; + +// Use the colors in your styles +const Button = styled.button` + background-color: ${(props) => props.theme.colors.blue4}; + color: ${(props) => props.theme.colors.blue11}; + border-color: ${(props) => props.theme.colors.blue7}; + &:hover { + background-color: ${(props) => props.theme.colors.blue5}; + border-color: ${(props) => props.theme.colors.blue8}; + } +`; + +// Wrap your app with the theme provider and apply your theme to it +export default function App() { + return ( + + + + ); +} +``` + +## emotion + +Usage with emotion is almost identical to the styled-components docs above, aside from the different imports. + +```js +import { + gray, + blue, + red, + green, + grayDark, + blueDark, + redDark, + greenDark, +} from "@radix-ui/colors"; +import { ThemeProvider } from "@emotion/react"; +import styled from "@emotion/styled"; +``` + +## vanilla-extract + +```js +import { + gray, + blue, + red, + green, + grayDark, + blueDark, + redDark, + greenDark, +} from "@radix-ui/colors"; +import { createTheme } from "@vanilla-extract/css"; + +export const [theme, vars] = createTheme({ + colors: { + ...gray, + ...blue, + ...red, + ...green, + }, +}); + +export const darkTheme = createTheme(vars, { + colors: { + ...grayDark, + ...blueDark, + ...redDark, + ...greenDark, + }, +}); + +// Use the colors in your styles +export const styles = { + button: style({ + backgroundColor: vars.colors.blue4, + color: vars.colors.blue11, + borderColor: vars.colors.blue7, + ":hover": { + backgroundColor: vars.colors.blue5, + borderColor: vars.colors.blue8, + }, + }), +}; + +// Apply your theme to it +export default function App() { + return ( + + + + ); +} +``` + +--- + +# Palette Composition + +## Composing a color palette + +A guide to composing a color palette with Radix Colors. + +# Composing a color palette + +A guide to composing a color palette with Radix Colors. + +## Choosing a brand scale + +Radix provides a number of scales you could use for your brand or accent color. + +Scales designed for white foreground text: + +### Custom brand colors + +Radix Colors are not intended to be customised. They’re designed to be accessible, well-balanced, and harmonious. Any customisation would likely break these features. + +If you need custom brand colors, we recommend adding custom scales alongside Radix scales. + +For example, you could use Radix Colors for your gray scale and your semantic scales, then add custom brand/accent colors. + +## Choosing a gray scale + +Radix Colors provides a pure gray and a few tinted gray scales. + +- `gray` is pure gray +- `mauve` is based on a purple hue +- `slate` is based on a blue hue +- `sage` is based on a green hue +- `olive` is based on a lime hue +- `sand` is based on a yellow hue + +### Neutral pairing + +If you want a neutral vibe, or you want to keep things simple, `gray` will work well with any hue or palette. + +### Natural pairing + +Alternatively, choose the gray scale which is saturated with the hue closest to your accent hue. The difference is subtle, but this will create a more colorful and harmonius vibe. + +## Choosing semantic scales + +For most projects, you will need colors to communicate semantic meaning. Here are some common pairings that work well in Western culture. + +- **Error**: `red`, `ruby`, `tomato`, `crimson` +- **Success**: `green`, `teal`, `jade`, `grass`, `mint` +- **Warning**: `yellow`, `amber`, `orange` +- **Info**: `blue`, `indigo`, `sky`, `cyan` + +In many cases, you might eventually need most of the scales, for one reason or another. Your app may support multiplayer mode, where you assign a color to each user. Your app may have a labelling feature, where your users assign a color to a task. Your app may use badges to communicate “pending” or “rejected” states. + +Radix Colors are well-balanced, and designed to work in harmony. So for product communication, most color pairings will work. + +## Choosing text scales + +Steps 11 and 12 are designed for low-contrast text and high-contrast text respectively. Depending on the vibe you want, you can use your accent scale or your gray scale. + +Using your accent scale will result in a more colorful vibe. + +Using your gray scale will result in a more functional vibe. + +The difference may seem subtle, but it can make a huge difference with a whole page of text. + +You may want to experiment with using your accent scale for text in your marketing sites, and your gray scale for text in your apps. + +--- + +## Scales + +See all accessible color scales that Radix Colors provides. + +# Scales + +An overview of all Radix Colors scales. + +#### Gray + +#### Mauve + +#### Slate + +#### Sage + +#### Olive + +#### Sand + +#### Gold + +#### Bronze + +#### Brown + +#### Yellow + +#### Amber + +#### Orange + +#### Tomato + +#### Red + +#### Ruby + +#### Crimson + +#### Pink + +#### Plum + +#### Purple + +#### Violet + +#### Iris + +#### Indigo + +#### Blue + +#### Cyan + +#### Teal + +#### Jade + +#### Green + +#### Grass + +#### Lime + +#### Mint + +#### Sky + +*** + +#### Overlays + +These scales are designed for overlays and don’t change across light and dark +theme. + +--- + +## Use cases + +How to use Radix Colors. + +# Understanding the scale + +Learn which scale step is the most appropriate for each use case. + +## Use cases + +There are 12 steps in each scale. Each step was designed for at least one specific use case. + +This table is a simple overview of the most common use case for each step. However, there are many exceptions and caveats to factor in, which are covered in further detail below. + +## Steps 1–2: Backgrounds + +Steps `1` and `2` are designed for app backgrounds and subtle component backgrounds. You can use them interchangeably, depending on the vibe you're going for. + +Appropriate applications include: + +- Main app background +- Striped table background +- Code block background +- Card background +- Sidebar background +- Canvas area background + +## Steps 3–5: Component backgrounds + +Steps `3`, `4`, and `5` are designed for UI component backgrounds. + +- Step `3` is for normal states. +- Step `4` is for hover states. +- Step `5` is for pressed or selected states. + +If your component has a transparent background in its default state, you can use Step `3` for its hover state. + +## Steps 6–8: Borders + +Steps `6`, `7`, and `8` are designed for borders. + +- Step `6` is designed for subtle borders on components which are not interactive. For example sidebars, headers, cards, alerts, and separators. +- Step `7` is designed for subtle borders on interactive components. +- Step `8` is designed for stronger borders on interactive components and focus rings. + +## Steps 9–10: Solid backgrounds + +Steps `9` and `10` are designed for solid backgrounds. + +Step `9` has the highest chroma of all steps in the scale. In other words, it's the purest step, the step mixed with the least amount of white or black. Because `9` is the purest step, it has a wide range of applications: + +- Website/App backgrounds +- Website section backgrounds +- Header backgrounds +- Component backgrounds +- Graphics/Logos +- Overlays +- Coloured shadows +- Accent borders + +Step `10` is designed for component hover states, where step `9` is the component's normal state background. + +## Steps 11–12: Text + +Steps `11` and `12` are designed for text. + +- Step `11` is designed for low-contrast text. +- Step `12` is designed for high-contrast text. + +--- \ No newline at end of file diff --git a/public/llms-full.txt b/public/llms-full.txt new file mode 100644 index 000000000..1b59d3ddc --- /dev/null +++ b/public/llms-full.txt @@ -0,0 +1,17672 @@ +# Radix UI - Complete Documentation + +> Radix UI is an open-source React component library for building high-quality, accessible design systems and web apps. + +--- + +# Radix Primitives - Complete Documentation + +> Radix Primitives is an open-source React component library for building high-quality, accessible design systems and web applications. Components are unstyled, accessible, and customizable. + +# Overview + +## Accessibility + +Radix Primitives follow the WAI-ARIA authoring practices guidelines and are tested in a wide selection of modern browsers and commonly used assistive technologies. + +# Accessibility + +Radix Primitives follow the WAI-ARIA authoring practices guidelines and are +tested in a wide selection of modern browsers and commonly used assistive +technologies. + +We take care of many of the difficult implementation details related to accessibility, including `aria` and `role` attributes, focus management, and keyboard navigation. That means that users should be able to use our components as-is in most contexts and rely on functionality to follow the expected accessibility design patterns. + +## WAI-ARIA + +[WAI-ARIA](https://www.w3.org/TR/wai-aria-1.2/), published and maintained by the W3C, specifies the semantics for many common UI patterns that show up in Radix Primitives. This is designed to provide meaning for controls that aren't built using elements provided by the browser. For example, if you use a `div` instead of a `button` element to create a button, there are attributes you need to add to the `div` in order to convey that it's a button for screen readers or voice recognition tools. + +In addition to semantics, there are behaviors that are expected from different types of components. A `button` element is going to respond to certain interactions in ways that a `div` will not, so it's up to the developer to reimplement those interactions with JavaScript. The [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.2/) provide additional guidance for implementing behaviors for various controls that come with Radix Primitives. + +## Accessible Labels + +With many built-in form controls, the native HTML `label` element is designed to provide semantic meaning and context for corresponding `input` elements. For non-form control elements, or for custom controls like those provided by Radix Primitives, [WAI-ARIA provides a specification](https://www.w3.org/TR/wai-aria-1.2/#namecalculation) for how to provide accessible names and descriptions to those controls. + +Where possible, Radix Primitives include abstractions to make labelling our controls simple. The [`Label`](../components/label) primitive is designed to work with many of our controls. Ultimately it's up to you to provide those labels so that users have the proper context when navigating your application. + +## Keyboard Navigation + +Many complex components, like [`Tabs`](../components/tabs) and [`Dialog`](../components/dialog), come with expectations from users on how to interact with their content using a keyboard or other non-mouse input modalities. Radix Primitives provide basic keyboard support in accordance with the [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.2/). + +## Focus Management + +Proper keyboard navigation and good labelling often go hand-in-hand with managing focus. When a user interacts with an element and something changes as a result, it's often helpful to move focus with the interaction so that the next tab stop is logical depending on the new context of the app. And for screen reader users, moving focus often results in an announcement to convey this new context, which relies on proper labelling. + +In many Radix Primitives, we move focus based on the interactions a user normally takes in a given component. For example, in [`AlertDialog`](../components/alert-dialog), when the modal is opened, focus is programmatically moved to a `Cancel` button element to anticipate a response to the prompt. + +--- + +## Getting started + +A quick tutorial to get you up and running with Radix Primitives. + +# Getting started + +A quick tutorial to get you up and running with Radix Primitives. + +## Implementing a Popover + +In this quick tutorial, we will install and style the [Popover](../components/popover) component. + +### 1. Install the primitive + +Install Radix Primitives from your command line. + +```bash +npm install radix-ui@latest +``` + +### 2. Import the parts + +Import and structure the parts. + +```jsx line=3,6-14 +// index.jsx +import * as React from "react"; +import { Popover } from "radix-ui"; + +const PopoverDemo = () => ( + + More info + + + Some more info… + + + + +); + +export default PopoverDemo; +``` + +### 3. Add your styles + +Add styles where desired. + +```jsx line=4,8,10,12 +// index.jsx +import * as React from "react"; +import { Popover } from "radix-ui"; +import "./styles.css"; + +const PopoverDemo = () => ( + + Show info + + + Some content + + + + +); + +export default PopoverDemo; +``` + +```css +/* styles.css */ +.PopoverTrigger { + background-color: white; + border-radius: 4px; +} + +.PopoverContent { + border-radius: 4px; + padding: 20px; + width: 260px; + background-color: white; +} + +.PopoverArrow { + fill: white; +} +``` + +### Demo + +Here's a complete demo. + +## Summary + +The steps above outline briefly what's involved in using a Radix Primitive in your application. + +These components are low-level enough to give you control over how you want to wrap them. You're free to introduce your own high-level API to better suit the needs of your team and product. + +In a few simple steps, we've implemented a fully accessible Popover component, without having to worry about many of its complexities. + +- Adheres to [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal) design pattern. +- Can be controlled or uncontrolled. +- Customize side, alignment, offsets, collision handling. +- Optionally render a pointing arrow. +- Focus is fully managed and customizable. +- Dismissing and layering behavior is highly customizable. + +--- + +## Introduction + +An open-source UI component library for building high-quality, accessible design systems and web apps. + +# Introduction + +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. + +## Vision + +Most of us share similar definitions for common UI patterns like accordion, checkbox, +combobox, dialog, dropdown, select, slider, and tooltip. These UI patterns are [documented by WAI-ARIA](https://www.w3.org/TR/wai-aria-practices/#aria_ex) and generally understood by the community. + +However, the implementations provided to us by the web platform are inadequate. They're +either non-existent, lacking in functionality, or cannot be customized sufficiently. + +So, developers are forced to build custom components; an incredibly difficult task. As a +result, most components on the web are inaccessible, non-performant, and lacking important +features. + +Our goal is to create a well-funded, open-source component library that the community can +use to build accessible design systems. + +## Key Features + +### Accessible + +Components adhere to the [WAI-ARIA design patterns](https://www.w3.org/TR/wai-aria-practices-1.2) where possible. We handle many of the difficult implementation details related to accessibility, including aria and role attributes, focus management, and keyboard navigation. Learn more in our [accessibility](./accessibility) overview. + +### Unstyled + +Components ship without styles, giving you complete control over the look and feel. Components can be styled with any styling solution. Learn more in our [styling](../guides/styling) guide. + +### Opened + +Radix Primitives are designed to be customized to suit your needs. Our open component architecture provides you granular access to each component part, so you can wrap them and add your own event listeners, props, or refs. + +### Uncontrolled + +Where applicable, components are uncontrolled by default but can also be controlled, alternatively. All of the behavior wiring is handled internally, so you can get up and running as smoothly as possible, without needing to create any local states. + +### Developer experience + +One of our main goals is to provide the best possible developer experience. Radix Primitives provides a fully-typed API. All components share a similar API, creating a consistent and predictable experience. We've also implemented an `asChild` prop, giving users full control over the rendered element. + +### Incremental adoption + +We recommend installing the `radix-ui` package and importing the primitives you need. This is the simplest way to get started, prevent version conflicts or duplication, and makes it easy to manage updates. The package is tree-shakeable, so you should only ship the components you use. + +```bash +npm install radix-ui +``` + +```tsx +import { Dialog, DropdownMenu, Tooltip } from "radix-ui"; +``` + +Alternatively, each primitive can be installed individually: + +```bash +npm install @radix-ui/react-dialog +npm install @radix-ui/react-dropdown-menu +npm install @radix-ui/react-tooltip +``` + +```tsx +import * as Dialog from "@radix-ui/react-dialog"; +import * as DropdownMenu from "@radix-ui/react-dropdown-menu"; +import * as Tooltip from "@radix-ui/react-tooltip"; +``` + +When installing separately, we recommend updating all Radix packages together to prevent duplication of shared dependencies and keep your bundle size down. + +## Community + +To get involved with the Radix community, ask questions and share tips, [Join our Discord](https://discord.com/invite/7Xb99uG). + +To receive updates on new primitives, announcements, blog posts, and general Radix tips, follow along on [Bluesky](https://bsky.app/profile/radix-ui.com) or [Twitter](https://twitter.com/radix_ui). + +To file issues, request features, and contribute, check out our GitHub. + +- [GitHub repo](https://github.com/radix-ui/primitives) +- [Code of conduct](https://github.com/radix-ui/primitives/blob/main/CODE_OF_CONDUCT.md) + +--- + +## Releases + +Radix Primitives releases and their changelogs. + +# Releases + +Radix Primitives releases and their changelogs. + +## May 5, 2025 + +This release introduces a brand new primitive in preview: [`PasswordToggleField`](../components/password-toggle-field). + +This new primitive provides components for rendering a password input alongside a button to toggle its visibility. Aside from its primary functionality, it also includes: + +- Returning focus to the input when toggling with a pointer +- Maintaining focus when toggling with keyboard or virtual navigation +- Resetting visibility to hidden after form submission to prevent accidental storage +- Implicit accessible labeling for icon-based toggle buttons + +This API is currently unstable, and we hope you'll help us test it out! Import the primitive using the `unstable_` prefix. + +```tsx +import { unstable_PasswordToggleField as PasswordToggleField } from "radix-ui"; + +export function PasswordField() { + return ( + + + + } + hidden={} + /> + + + ); +} +``` + +### Other updates + +- Add unstable `Provider`, `Trigger` and `BubbleInput` parts to Checkbox ([#3459](https://github.com/radix-ui/primitives/pull/3459)) +- Update default input type to `text` and pass to the underlying input element ([#3510](https://github.com/radix-ui/primitives/pull/3510)) + +## April 22, 2025 + +- Update the dependency for `use-sync-external-store` to ensure entrypoint is valid + +## April 17, 2025 + +This release introduces a brand new primitive in preview: [`OneTimePasswordField`](../components/one-time-password-field). + +This new group of components are designed to implement a common design pattern for one-time password fields displayed as separate input fields for each character. This UI is deceptively complex to implement in such a way that interactions follow user expectations. The new primitive handles all of this complexity for you, including: + +- Keyboard navigation mimicking the behavior of a single input field +- Overriding values on paste +- Password manager autofill support +- Input validation for numeric and alphanumeric values +- Auto-submit on completion +- Focus management +- Hidden input to provide a single value to form data + +As this is a preview release, **the API is currently unstable**. We hope you'll help us test it out and let us know how it goes. + +Import the primitive using the `unstable_` prefix. + +```tsx +import { unstable_OneTimePasswordField as OneTimePasswordField } from "radix-ui"; + +export function Verify() { + return ( + + + + + + + + + + ); +} +``` + +### Other updates + +- All form controls with internal bubble inputs now use the Radix `Primitive` component by default. This will allow us to expose these components in a future release so users can better control this behavior in the future. +- Minor improvements to `useControllableState` to enhance performance, reduce surface area for bugs, and log warnings when misused + +## April 8, 2025 + +- Improved rendering performance for the Tooltip provider +- Ensure Tooltip is closed when `pointerdown` is fired on the trigger +- Add support for `crossOrigin` in Avatar images +- Fix Avatar flashing when an image is already cached +- Improve `displayName` for better debugging of slottable components + +## February 5, 2025 + +- Updated dependencies to remove peer dependency warnings for `react` and `react-dom` +- Skip forwarding refs to `SlotClone` when the child is a `Fragment` + +## January 22, 2025 + +- Added a `radix-ui` package that exposes the latest version of all Radix Primitives from a single place. This tree-shakable entrypoint makes it easier to bring in whatever components you need and keep them up-to-date without worrying about conflicting or duplicate dependencies. +- Updated `aria-hidden` and `react-remove-scroll` dependencies for the following components: + - Alert Dialog + - Context Menu + - Dialog + - Dropdown Menu + - Hover Card + - Menubar + - Navigation Menu + - Popover + - Select + - Toast + - Tooltip + +## October 1, 2024 + +- Fix `allowPinchZoom` bug for trackpad users + +* Check for `referrerPolicy` when checking the image loading status + +- Fix a bug where `defaultChecked` unexpectedly changed for uncontrolled checkboxes +- Forward the `form` prop to the bubble input element to fix non-parent form submissions + +* Fix `allowPinchZoom` bug for trackpad users + +- Forward the `form` prop to the bubble input element to fix non-parent form submissions + +* Fix `asChild` prop not working as expected on the `Viewport` +* Update internal styles to fix other issues with `Viewport` + +- Fix error thrown when items are initially undefined +- Fix several bugs for touch devices +- Forward the `form` prop to the bubble input element to fix non-parent form submissions +- Fix position bug where popover may start off-screen for long items + +* Forward the root `form` prop to each thumb's bubble input element to fix non-parent form submissions + +- Forward the `form` prop to the bubble input element to fix non-parent form submissions + +* Fix incorrect focus when `hotkey` is an empty array + +## June 28, 2024 + +- Export `CheckedState` type + +* Export `TooltipProviderProps` type + +## June 21, 2024 + +- Add a missing internal utility to `package.json`. The corresponding packages that provide a Portal part also received a patch update. + +## June 19, 2024 + +Released minor versions for all primitives with the following changes: + +- Full React 19 compatability +- Full RSC compatibility +- Internal build tooling changes +- Update and pin `react-remove-scroll` dependency version to avoid double scrollbar bugs in edge cases +- Don’t scroll menu items in response to hover +- Make sure that components that close on Escape key press capture the corresponding keyboard event. This way you can call `stopPropagation` in `onEscapeKeyDown` if you need more control rendering Radix components within another component that closes on Escape key press. +- Make sure that components with roving focus do not interfere with browser or system hotkeys, such as back navigation +- Make sure that components that support `hideWhenDetached` prop do not allow interactions with hidden content + +* Log an error when an accessible title via the `Dialog.Title` part is missing +* Log a warning when an accessible description via the `Dialog.Description` part is missing + +- Make sure that the component doesn’t interfere when clicking on the spinner of a number input + +* Remove unsupported `disableOutsidePointerEvents` prop + +- Fix hydration error in SSR on the initial render + +* Explicitly allow `value={undefined}` to represent an indeterminate state, matching the current practical behaviour + +- Add `nonce` prop to be able to pass CSP nonce to the inline styles + +* Add `nonce` prop to be able to pass CSP nonce to the inline styles + +## September 25, 2023 + +- Fix pointer-events issue when clicking outside +- Fix `Portal` part types lying about accepting DOM props + +* Prevent image flash + +- Fix pointer-events issue when clicking outside +- Fix `Portal` part types lying about accepting DOM props + +* Fix pointer-events issue when clicking outside +* Fix `Portal` part types lying about accepting DOM props + +- Fix pointer-events issue when clicking outside +- Fix `Portal` part types lying about accepting DOM props + +* Fix pointer-events issue when clicking outside +* Fix `Portal` part types lying about accepting DOM props + +- Fix pointer-events issue when clicking outside +- Fix `Portal` part types lying about accepting DOM props + +* Fix pointer-events issue when clicking outside +* Fix `Portal` part types lying about accepting DOM props + +- Fix pointer-events issue when clicking outside +- Fix `Portal` part types lying about accepting DOM props +- Fix `Popover` nested inside `Dialog` not opening + +* Add `scroll-behavior: smooth` compatibility + +- **\[Breaking]** Add ability to reset to placeholder using `""` `value`. Note that this is only a breaking change if you were using an option with a `value` of `""`. +- Fix pointer-events issue when clicking outside +- Fix `Portal` part types lying about accepting DOM props + +* Fix pointer-events issue when clicking outside + +- Fix pointer-events issue when clicking outside +- Fix `Portal` part types lying about accepting DOM props +- Fix issue with boundary padding calculations +- Add option to always re-position `Content` on the fly + +## May 26, 2023 + +This release ensures all of our primitives are ESM compatible. We have also updated to the latest version of [Floating UI](https://floating-ui.com/) for all of our popper-positioned primitives. + +- Improve ESM compatibility +- Fix possible upstream compiler errors (`@types/react` phantom dependency) + +* Position content correctly when matching trigger size + +- Prevent non-modal dialog from re-opening when closing using trigger in Safari +- Ensure focus trapping is maintained when the focused item is deleted + +* Position content correctly when matching trigger size + +- Position content correctly when matching trigger size + +* Position content correctly when matching trigger size + +- Do not close when clicking items and meta key is down + +* Position content correctly when matching trigger size +* Prevent non-modal popover from re-opening when closing using trigger in Safari +* Ensure `--radix-popper-available-width` is calculated correctly when using `collisionBoundary` + +- Position content correctly when matching trigger size +- Improve scroll buttons touch screen support + +* Clamp thumb position within range + +- Ensure `Slot` can be used in a React Server Component + +* Position content correctly when matching trigger size +* Improve large content hoverability + +## March 8, 2023 + +This release introduces a brand new primitive in preview: [`Form`](../components/form). + +- New primitive + +## February 24, 2023 + +- Reset checkbox state when form is reset + +* Expose new CSS custom properties to enable size constraints +* Don't exit fullscreen mode when pressing escape to dismiss from submenu +* Relax `onCheckedChange` type on `ContextMenu.CheckboxItem` + +- Expose new CSS custom properties to enable size constraints +- Don't exit fullscreen mode when pressing escape to dismiss from submenu +- Relax `onCheckedChange` type on `DropdownMenu.CheckboxItem` + +* Expose new CSS custom properties to enable size constraints + +- Expose new CSS custom properties to enable size constraints +- Don't exit fullscreen mode when pressing escape to dismiss from submenu +- Relax `onCheckedChange` type on `Menubar.CheckboxItem` + +* Expose new CSS custom properties to enable size constraints + +- Expose new CSS custom properties to enable size constraints + +## January 17, 2023 + +This release introduces a brand new primitive: [`Menubar`](../components/menubar). It also adds support for a highly requested feature for [`Select`](../components/select): the ability to position the content in a similar way to `Popover` or `DropdownMenu`. + +- Add horizontal orientation support with new `orientation` prop, as well as RTL support with `dir` + +* Fix consistency issue with RTL positioning + +- Fix consistency issue with RTL positioning + +* Fix consistency issue with RTL positioning + +- New primitive + +* Fix consistency issue with RTL positioning + +- Add `position` prop to `Select.Content` to enable popper positioning + +* Fix consistency issue with RTL positioning + +## December 14, 2022 + +- Add `disabled` prop to `ContextMenu.Trigger` + +## November 15, 2022 + +- Fix invalid `pointerId` in Cypress when running Firefox + +## October 17, 2022 + +- Fix initial animation playback in Firefox and Safari + +* Fix issue with textarea elements not being scrollable in Firefox + +- Fix initial animation playback in Firefox and Safari + +* **\[Breaking]** Add support for indeterminate state on `ContextMenu.CheckboxItem`. Note that this is only a breaking change if you are currently using the `CheckboxItem` part and your codebase is written in TypeScript. + +- Fix issue with textarea elements not being scrollable in Firefox + +* **\[Breaking]** Add support for indeterminate state on `DropdownMenu.CheckboxItem`. Note that this is only a breaking change if you are currently using the `CheckboxItem` part and your codebase is written in TypeScript. +* Correctly pair `DropdownMenu.Trigger` open state with `aria-expanded` when closed +* Fix issue with eager selection of items when using `asChild` +* Fix issue with dismissing when the component is used in a separate popup window + +- Improve text selection experience + +* **\[Breaking]** Remove `useLabelContext` and support for fully custom controls. For native labelling to work, ensure your custom controls are based on native elements such as `button` or `input`. +* Improve native behavior by using the native `label` element + +- Prevent menu from re-opening with the pointer after being dismissed with escape +- Add `delayDuration` and `skipDelayDuration` props to `NavigationMenu.Root`. Note that by default, triggers now have a brief delay before opening in order to improve UX, this can be modified using the props provided. + +* Add `disabled` prop to `RadioGroup.Root` +* Fix issue where `RadioGroup.Root` was focusable when all items were disabled + +- Add `disabled` prop to `Select.Root` +- Add `required` prop to `Select.Root` + +* Add ability to visually invert the slider using the new `inverted` prop on `Slider.Root` +* Add `onValueCommit` prop to `Slider.Root` to better handle discrete value changes + +- Stop eagerly creating callback props + +* Fix regression with screen readers announcing as "group" rather than "status" +* Fix regression with `ref` assignments on child elements returning `null` +* Add `onPause` and `onResume` props to `Toast.Root` +* Fix timer reset issue which would cause toasts to dismiss early in some cases + +- Prevent `Toolbar.Item` click handlers firing twice + +* Ensure tooltip doesn't open if interacting with the trigger before the open timer expires + +## July 21, 2022 + +With this release, we start following semantic versioning strictly. All primitives are now versioned . + +We also move the [`Select`](../components/select), [`Toast`](../components/toast) and [`NavigationMenu`](../components/navigation-menu) from preview to stable. + +- Improve support for React 18 +- **\[Breaking]** Improve RTL performance. You need to use [`DirectionProvider`](../utilities/direction-provider) if you were relying on `dir` attribute inheritance from document (or any element). + +* **\[Breaking]** Remove `allowPinchZoom` prop, now defaults to `true` +* Improve compatibility with JS animation libraries with `forceMount` on `AlertDialog.Portal` +* Fix regressions with page interactivity while/after closing dialog + +- **\[Breaking]** Improve indirect nesting of context menus. Submenus must now be created using explicit parts. +- **\[Breaking]** Remove `allowPinchZoom` prop, now defaults to `true` +- **\[Breaking]** Add new `Portal` part. To avoid regressions, use this part if you want portalling behavior. Note that `z-index` isn't managed anymore so you have full control of layering. +- **\[Breaking]** Remove `offset` on `Arrow` part +- **\[Breaking]** Rename `collisionTolerance` to `collisionPadding` on `Content` part and accepts a number or a padding object +- Fix issue with native context menu appearing in React 18 +- Add `data-highlighted` attribute to support styling +- Add `data-state` attribute to `Trigger` part +- Add `collisionBoundary`, `arrowPadding`, `sticky`, `hideWhenDetached` props on `Content` part + +* **\[Breaking]** Remove `allowPinchZoom` prop, now defaults to `true` +* Improve compatibility with JS animation libraries with `forceMount` on `Dialog.Portal` +* Fix regressions with page interactivity while/after closing dialog + +- **\[Breaking]** Improve indirect nesting of dropdown menus. Submenus must now be created using explicit parts. +- **\[Breaking]** Remove `allowPinchZoom` prop, now defaults to `true` +- **\[Breaking]** Add new `Portal` part. To avoid regressions, use this part if you want portalling behavior. Note that `z-index` isn't managed anymore so you have full control of layering. +- **\[Breaking]** Remove `offset` on `Arrow` part +- **\[Breaking]** Rename `collisionTolerance` to `collisionPadding` on `Content` part and accepts a number or a padding object +- Add `data-highlighted` attribute to support styling +- Prevent escape key from exiting fullscreen mode in Firefox & Safari +- Add `collisionBoundary`, `arrowPadding`, `sticky`, `hideWhenDetached` props on `Content` part + +* **\[Breaking]** Add new `Portal` part. To avoid regressions, use this part if you want portalling behavior. Note that `z-index` isn't managed anymore so you have full control of layering. +* **\[Breaking]** Remove `offset` on `Arrow` part +* **\[Breaking]** Rename `collisionTolerance` to `collisionPadding` on `Content` part and accepts a number or a padding object +* Add `collisionBoundary`, `arrowPadding`, `sticky`, `hideWhenDetached` props on `Content` part + +- Ensure menu closes after clicking `NavigationMenu.Link` +- Add `onSelect` prop to `NavigationMenu.Link` + +* **\[Breaking]** Remove `allowPinchZoom` prop, now defaults to `true` +* **\[Breaking]** Add new `Portal` part. To avoid regressions, use this part if you want portalling behavior. Note that `z-index` isn't managed anymore so you have full control of layering. +* **\[Breaking]** Remove `offset` on `Arrow` part +* **\[Breaking]** Rename `collisionTolerance` to `collisionPadding` on `Content` part and accepts a number or a padding object +* Add `collisionBoundary`, `arrowPadding`, `sticky`, `hideWhenDetached` props on `Content` part + +- **\[Breaking]** Note that `z-index` isn't managed anymore so you have full control of layering. The prop to provide a custom container evolves from `containerRef` (ref) to `container` (element). The `data-radix-portal` was removed because you can use `asChild` to control the element. + +* Add `aria-required` to root + +- `ScrollArea.Thumb` is now animatable + +* **\[Breaking]** Renamed `data-state` values from `active|inactive` to `checked|unchecked` +* **\[Breaking]** Add new `Portal` part. To avoid regressions, use this part if you want portalling behavior. Note that `z-index` isn't managed anymore so you have full control of layering. +* Fix position breaking when using `asChild` on `Select.Content` +* Improve trigger/content alignment when `Select.Content` has padding +* Fix trigger/content alignment when there are less than 5 items +* Support trigger/content alignment when no value is provided +* Add `data-highlighted` attribute to support styling +* Add support for placeholder via `placeholder` prop on `Select.Value` +* Resolve value mismatch with underlying native select + +- Fix issue with children ordering when using `Slottable` + +* Add support for lifecycle animation to `Tabs.Content` + +- **\[Breaking]** The default toast order has changed, they now render top to bottom from oldest to newest +- Improve Typescript types when using `asChild` +- Fix issue with toast reordering when updating React's `key` prop +- Improve compatability with animation libraries + +* **\[Breaking]** Add new `Portal` part. To avoid regressions, use this part if you want portalling behavior. Note that `z-index` isn't managed anymore so you have full control of layering. +* **\[Breaking]** By default `Tooltip.Content` will remain open when hovering (WCAG 2.1 Content on Hover compliance). `disableHoverableContent` can be supplied to `Tooltip.Provider` to restore previous behavior +* **\[Breaking]** `side` on `Tooltip.Content` now defaults to `top` +* **\[Breaking]** `Tooltip.Provider` is now required, you must wrap your app to avoid regressions. +* **\[Breaking]** Remove `offset` on `Arrow` part +* **\[Breaking]** Rename `collisionTolerance` to `collisionPadding` on `Content` part and accepts a number or a padding object +* Improve layering of tooltip with other primitives +* Fix tooltip closing when transforming/animation trigger +* Add `collisionBoundary`, `arrowPadding`, `sticky`, `hideWhenDetached` props on `Content` part + +## February 28, 2022 + +This release introduces 3 brand new primitives in preview: [`Select`](../components/select), [`Toast`](../components/toast) and [`NavigationMenu`](../components/navigation-menu), whilst also shipping a ton of fixes and improvements. + +- Prevent form submission when pressing `Accordion.Trigger` +- Fix animation issue with React 18 + +* Improve pointer-events management + +- Prevent activation via enter key + +* Fix animation issue with React 18 + +- Prevent `DropdownMenu.TriggerItem` click from firing twice +- Improve idle performance + +* Improve pointer-events management +* **\[Breaking]** `Dialog.Title` is now a required part so will throw an error if not used. `aria-describedby={undefined}` must be passed to `Dialog.Content` if no description is needed. + +- Improve composability with `Dialog`/`AlertDialog` +- Prevent clicking trigger to close from immediately reopening in non-modal mode +- Prevent `DropdownMenu.TriggerItem` click from firing twice +- Improve idle performance + +* New primitive + +- Prevent activation via enter key + +* New primitive + +- Prevent page scroll when using `Home` and `End` keys + +* Prevent accidental focus activation via right click + +- New primitive + +* Improve accessibility by using radio role for single toggle group + +## December 13, 2021 + +This release focuses on React 18 support and introduces a number of breaking changes to some packages, mostly related to portalling dialogs. + +- **\[Breaking]** Deprecate `IdProvider`. Improves support for React 18 going forward and is no longer needed in older versions. Remove from your app to avoid deprecation warnings. + +* Improve React 18 support +* Improve dev mode errors with mismatched `type` and `value` props +* Prevent `Accordion.Content` height animation on initial page load + +- **\[Breaking]** Add new `Portal` part. To avoid regressions, use this part if you want portalling behavior. +- **\[Breaking]** Support scrolling within `AlertDialog.Overlay`. Move `allowPinchZoom` to root. +- Fix `asChild` TypeScript error + +* Prevent `Collapsible.Content` height animation on initial page load + +- **\[Breaking]** Add new `Portal` part. To avoid regressions, use this part if you want portalling behavior. +- **\[Breaking]** Support scrolling within `Dialog.Overlay`. Move `allowPinchZoom` to root. + +* Prevent disabled trigger from opening menu + +- Fix ability to focus `HoverCard` when inside a dialog + +* Prevent programmatic focus from changing value + +- **\[Breaking]** Change `Tabs.Trigger` to `button` element +- Improve TSDocs + +* Remove invalid `aria-orientation` attribute on `role=group` element + +- Fix `asChild` TypeScript error +- Remove invalid `toolbaritem` role + +* **\[Breaking]** Add new `TooltipProvider` part. You must wrap your app to avoid regressions. +* **\[Breaking]** Remove `type=button` attribute from `Tooltip.Trigger` +* Fix tooltip activation regression + +- Fix `key` warnings + +## October 15, 2021 + +- All primitives are now versioned +- Fix composability issues between primitives by scoping context +- Fix CSS unmount animations + +* Add new CSS variable to `Accordion.Content` to help with width animations + +- Improve composability with `Dialog` +- **\[Breaking]** Remove `AlertDialog.Content` `onInteractOutside` prop + +* Improve composability with `AlertDialog` +* Add pinch to zoom support to `DropdownMenu.Content` via `allowPinchZoom` prop + +- Add pinch to zoom support to `ContextMenu.Content` via `allowPinchZoom` prop +- Prevent scroll via arrow keypress on submenu triggers + +* Add new CSS variable to `Collapsible.Content` to help with width animations + +- Prevent screen reader virtual cursor from accessing hidden input + +* Improve composability with `Tooltip` +* Add pinch to zoom support to `DropdownMenu.Content` via `allowPinchZoom` prop +* Prevent scroll via arrow keypress on submenu triggers + +- Open on focus to improve keyboard support +- Compose correct pointer events internally + +* Allow its children to prevent event propagation + +- Prevent screen reader virtual cursor from accessing hidden inputs + +* Add pinch to zoom support to `Popover.Content` via `allowPinchZoom` prop + +- Fix calculations when value is `0` + +* Prevent screen reader virtual cursor from accessing hidden input + +- **\[Breaking]** Unmount content within `Tabs.Content` when tab is inactive + +## September 7, 2021 + +- All primitives moved to **Beta** and are now versioned +- **\[Breaking]** Replace polymorphic `as` prop with `asChild` boolean prop. Learn more + about how to [change the rendered element here](/primitives/docs/guides/composition) + +* Improve composability with `DropdownMenu` + +- Improve composability with `Dialog` +- Re-enable `pointer-events` when closed +- Prevent body text from selecting on close (Firefox) +- Ensure sub triggers receive focus on click (iOS Safari) + +* **\[Breaking]** Deprecate `extendPrimitive` utility + +## August 4, 2021 + +- Improve polymorphic types performance + +* **\[Breaking]** Remove `AlertDialog.Content` `onPointerDownOutside` prop +* Prevent outside pointer events triggering prematurely on touch devices + +- Add modality support via `modal` prop +- **\[Breaking]** Remove `ContextMenu.Content` `disableOutsidePointerEvents` prop +- Prevent outside pointer events triggering prematurely on touch devices + +* Add modality support via `modal` prop +* Improve animation rendering in React 18 +* Ensure focus is restored to trigger on close when using the `autofocus` attribute on a child element +* Prevent outside pointer events triggering prematurely on touch devices +* Ensure iOS Safari consistently focuses the first focusable element + +- Add modality support via `modal` prop +- **\[Breaking]** Remove `DropdownMenu.Content` `disableOutsideScroll` prop +- **\[Breaking]** Remove `DropdownMenu.Content` `disableOutsidePointerEvents` prop +- Prevent outside pointer events triggering prematurely on touch devices + +* Add modality support via `modal` prop +* **\[Breaking]** Remove `Popover.Content` `disableOutsideScroll` prop +* **\[Breaking]** Remove `Popover.Content` `disableOutsidePointerEvents` prop +* **\[Breaking]** Remove `Popover.Content` `trapFocus` prop +* Improve animation rendering in React 18 +* Ensure focus is restored to trigger on close when using the `autofocus` attribute on a child element +* Prevent outside pointer events triggering prematurely on touch devices +* Ensure iOS Safari consistently focuses the first focusable element + +- Add `data-state` to `ScrollBar` part + +* Prevent thumb receiving focus when disabled +* Prevent focus loss on thumb when using `React.StrictMode` + +## June 24, 2021 + +- Can now be triggered on touch with a long press + +* Add optional `Title` and `Description` parts for simpler labelling + +- Add `data-orientation` to `Scrollbar` for styling convenience +- Fix `forceMount` type issue on `Scrollbar` + +* Ensure the correct thumb is focused when using keyboard and crossing another thumb +* Ensure only one arrow press is needed when crossing another thumb + +- Improve types compatibility + +* Ensure only one click is needed to toggle a single controlled toggle group +* Ensure focus behavior is consistent on Safari + +## June 15, 2021 + +- Improve polymorphic types + +* **\[Breaking]** Rename `Accordion.Button` to `Accordion.Trigger` +* **\[Breaking]** Rename `Accordion.Panel` to `Accordion.Content` +* **\[Breaking]** Rename custom property accordingly (`--radix-accordion-content-height`) +* **\[Breaking]** `type=“single”` `Accordion` now has a new `collapsible` prop which is `false` by default. This means that the default behavior has now changed. By default a user cannot close all items. + +- **\[Breaking]** Allow preventing default in `onPointerDownOutside` without inadvertently preventing focus + +* **\[Breaking]** `onCheckedChange(event)` is now `onCheckedChange(checked: CheckedState)` +* Improve compatibility with native form validation +* Allow stopping propagation on `Checkbox` `onClick` +* Improve compatibility with native `label` +* Improve accessibility when wrapped in native `label` + +- **\[Breaking]** Rename `Collapsible.Button` to `Collapsible.Trigger` + +* Add submenu support +* Add `ContextMenu.TriggerItem` +* Add `ContextMenu.Arrow` +* Add `dir` prop for RTL support with submenus +* **\[Breaking]** Allow preventing default in `onPointerDownOutside` without inadvertently preventing focus +* **\[Breaking]** Remove `ContextMenu.Content` `side` prop +* **\[Breaking]** Remove `ContextMenu.Content` `align` prop +* **\[Breaking]** If you had `sideOffset` on `ContextMenu.Content` before, you should now use `alignOffset`. This is to standardize vertical alignment for both root and sub-menus. +* **\[Breaking]** `onFocusOutside` is now a custom event +* Improve support of content and item with no padding +* Align with WAI-ARIA spec by focusing first item when opening via keyboard + +- **\[Breaking]** Allow preventing default in `onPointerDownOutside` without inadvertently preventing focus + +* Add submenu support +* Add `DropdownMenu.TriggerItem` +* Add `dir` prop for RTL support with submenus +* **\[Breaking]** Allow preventing default in `onPointerDownOutside` without inadvertently preventing focus +* **\[Breaking]** `onFocusOutside` is now a custom event +* **\[Breaking]** The up arrow no longer opens the menu +* Align with WAI-ARIA spec by focusing first item when opening via keyboard + +- **\[Breaking]** Allow preventing default in `onPointerDownOutside` without inadvertently preventing focus +- **\[Breaking]** `onFocusOutside` is now a custom event + +* **\[Breaking]** `onValueChange(event)` is now `onValueChange(value: string)` +* **\[Breaking]** Remove `RadioGroup.Item` `onCheckedChange` prop +* Improve compatibility with native form validation +* Improve usage within forms + +- Brand new version with a simpler API +- Improve Safari support +- Improve RTL support +- Improve touch support +- `Scrollbar` mount/unmount can now be animated +- Add minimum width/height to thumb so it's always grabbable +- Move functional CSS into component to improve DX +- Bundle size significantly reduced +- **\[Breaking]** Remove `overflowX` and `overflowY` props +- **\[Breaking]** Remove `ScrollAreaButtonStart`, `ScrollAreaButtonEnd` and `ScrollAreaTrack` +- **\[Breaking]** Rename `scrollbarVisibility` prop to `type`. The values are `auto`, `always`, `scroll` or `hover` +- **\[Breaking]** Rename `scrollbarVisibilityRestTimeout` prop to `scrollHideDelay` +- **\[Breaking]** Remove `trackClickBehavior` prop as we've removed built-in animation. Clicking on track always snaps to pointer position +- **\[Breaking]** `ScrollAreaScrollbarX` and `ScrollAreaScrollbarY` are now `` and `` +- Ensure no scrollbars are shown when scrolling is disabled +- Ensure children event handlers don't break +- Ensure scroll area updates when children content size changes + +* Improve usage within forms +* Fix key binding issue in LTR + +- **\[Breaking]** `onCheckedChange(event)` is now `onCheckedChange(checked: boolean)` +- Improve compatibility with native form validation +- Improve usage within forms +- Improve accessibility when wrapped in native `label` + +* **\[Breaking]** Rename `Tabs.Tab` to `Tabs.Trigger` +* **\[Breaking]** Rename `Tabs.Panel` to `Tabs.Content` + +## May 3, 2021 + +- Improve polymorphic types performance + +* Ensure only one click is needed to close a single controlled accordion + +- **\[Breaking]** Remove `readOnly` prop + +* Add `onOpenChange` prop + +- Ensure focus position isn't lost when blurring out window and re-focusing it + +* Take into account non-visible items +* **\[Breaking]** Remove `anchorRef` prop +* Prevent page from scrolling when selecting an item with space key + +- New primitive + +* **\[Breaking]** Remove `anchorRef` prop and replace with optional `Anchor` part + +- Add optional `orientation`, `dir`, `loop` props +- **\[Breaking]** Remove `readOnly` prop + +* **\[Breaking]** Remove `readOnly` prop + +- Add optional `orientation`, `dir`, `loop` props + +* **\[Breaking]** Remove `anchorRef` prop + +## March 26, 2021 + +- Improve tree-shaking + +* Ensure you can open a context menu when one is already open + +- Fix potential overlap issue + +* Ensure `Content` closes when it has multiple close animations + +- **\[Breaking]** Rename `ToggleButton` primitive to `Toggle` +- **\[Breaking]** Rename `toggled` prop to `pressed` +- **\[Breaking]** Rename `defaultToggled` prop to `defaultPressed` +- **\[Breaking]** Rename `onToggledChange` prop to `onPressedChange` + +* New primitive + +- New primitive + +* Add custom timing support +* Add unmount animation support + +## March 5, 2021 + +- Add height CSS custom property to panel for easier animation + +* Add height CSS custom property to content for easier animation + +- Fix type definition conflicts + +## March 3, 2021 + +- Add support for SSR +- **\[Breaking]** Remove `selector` prop and `data-radix-*` atributes + +* **\[Breaking]** Add support for multiple values. Note that this is a breaking change because the new `type` prop is required + +- Ensure `step` is rounded correctly + +* Add RTL support (`dir` prop) + +## February 17, 2021 + +- Ensure events are composed when using `` + +## February 15, 2021 + +- Expose `onCloseAutoFocus` prop + +* Expose `onCloseAutoFocus` prop + +## February 10, 2021 + +- Fix type autocompletion when using `as` prop + +* Prevent open/close flickering + +- Ensure focus is returned properly on close + +* **\[Breaking]** Move `name` prop from `Item` to `Root` + +## February 1, 2021 + +- Re–add missing `children` + +* Re–add missing `children` + +- Prevent flickering (sliding) issue + +## January 29, 2021 + +- New utility + +## January 25, 2021 + +- Fix regression when tabbing out would close + +* Fix broken arrow keys navigation + +## January 22, 2021 + +- Add `selector` prop + +* Ensure setting `disabled={false}` on `Root` doesn't enable disabled items + +- Add enter key support on trigger +- Prevent focus race condition + +* Ensure `Content` repositions on window resize +* Ensure last element inside `Content` triggers blur event + +## December 15, 2020 + +- Initial release! 🎉 + +--- + +# Guides + +## Animation + +Animate Radix Primitives with CSS keyframes or the JavaScript animation library of your choice. + +# Animation + +Animate Radix Primitives with CSS keyframes or the JavaScript animation +library of your choice. + +Adding animation to Radix Primitives should feel similar to any other component, but there are some caveats noted here in regards to exiting animations with JS animation libraries. + +## Animating with CSS animation + +The simplest way to animate Primitives is with CSS. + +You can use CSS animation to animate both mount and unmount phases. The latter is possible because the Radix Primitives will suspend unmount while your animation plays out. + +```css +@keyframes fadeIn { + from { + opacity: 0; + } + to { + opacity: 1; + } +} + +@keyframes fadeOut { + from { + opacity: 1; + } + to { + opacity: 0; + } +} + +.DialogOverlay[data-state="open"], +.DialogContent[data-state="open"] { + animation: fadeIn 300ms ease-out; +} + +.DialogOverlay[data-state="closed"], +.DialogContent[data-state="closed"] { + animation: fadeOut 300ms ease-in; +} +``` + +## Delegating unmounting for JavaScript Animation + +When many stateful Primitives are hidden from view, they are actually removed from the React Tree, and their elements removed from the DOM. JavaScript animation libraries need control of the unmounting phase, so we provide the `forceMount` prop on many components to allow consumers to delegate the mounting and unmounting of children based on the animation state determined by those libraries. + +For example, if you want to use React Spring to animate a `Dialog`, you would do so by conditionally rendering the dialog `Overlay` and `Content` parts based on the animation state from one of its hooks like `useTransition`: + +```jsx +import { Dialog } from "radix-ui"; +import { useTransition, animated, config } from "react-spring"; + +function Example() { + const [open, setOpen] = React.useState(false); + const transitions = useTransition(open, { + from: { opacity: 0, y: -10 }, + enter: { opacity: 1, y: 0 }, + leave: { opacity: 0, y: 10 }, + config: config.stiff, + }); + return ( + + Open Dialog + {transitions((styles, item) => + item ? ( + <> + + + + + +

Hello from inside the Dialog!

+ close + + + + ) : null, + )} + + ); +} +``` + +--- + +## Composition + +Use the `asChild` prop to compose Radix's functionality onto alternative element types or your own React components. + +# Composition + +Use the `asChild` prop to compose Radix's functionality onto alternative +element types or your own React components. + +All Radix primitive parts that render a DOM element accept an `asChild` prop. When `asChild` is set to `true`, Radix will not render a default DOM element, instead cloning the part's child and passing it the props and behavior required to make it functional. + +## Changing the element type + +In the majority of cases you shouldn’t need to modify the element type as Radix has been designed to provide the most appropriate defaults. However, there are cases where it is helpful to do so. + +A good example is with `Tooltip.Trigger`. By default this part is rendered as a `button`, though you may want to add a tooltip to a link (`a` tag) as well. Let's see how you can achieve this using `asChild`: + +```jsx line=7 +import * as React from "react"; +import { Tooltip } from "radix-ui"; + +export default () => ( + + + Radix UI + + … + +); +``` + +> If you do decide to change the underlying element type, it is your responsibility to ensure it remains accessible and functional. In the case of `Tooltip.Trigger` for example, it must be a focusable element that can respond to pointer and keyboard events. If you were to switch it to a `div`, it would no longer be accessible. + +In reality, you will rarely modify the underlying DOM element like we've seen above. Instead it's more common to use your own React components. This is especially true for most `Trigger` parts, as you usually want to compose the functionality with the custom buttons and links in your design system. + +## Composing with your own React components + +This works exactly the same as above, you pass `asChild` to the part and then wrap your own component with it. +However, there are a few gotchas to be aware of. + +### Your component must spread props + +When Radix clones your component, it will pass its own props and event handlers to make it functional and accessible. If your component doesn't support those props, it will break. + +This is done by spreading all of the props onto the underlying DOM node. + +```jsx line=5 +// before +const MyButton = () => + + + + + ); +}; +``` + +### Custom portal container + +Customise the element that your alert dialog portals into. + +```jsx line=2,13 +export default () => { + const [container, setContainer] = React.useState(null); + return ( +
+ + + + + ... + + + +
+
+ ); +}; +``` + +## Accessibility + +Adheres to the [Alert and Message Dialogs WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog). + +### Keyboard Interactions + +--- + +## Aspect Ratio + +Displays content within a desired ratio. + +# Aspect Ratio + +Displays content within a desired ratio. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-aspect-ratio +``` + +## Anatomy + +Import the component. + +```jsx +import { AspectRatio } from "radix-ui"; + +export default () => ; +``` + +## API Reference + +### Root + +Contains the content you want to constrain to a given ratio. + +--- + +## Avatar + +An image element with a fallback for representing the user. + +# Avatar + +An image element with a fallback for representing the user. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-avatar +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Avatar } from "radix-ui"; + +export default () => ( + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of an avatar. + +### Image + +The image to render. By default it will only render when it has loaded. You can use the `onLoadingStatusChange` handler if you need more control. + +### Fallback + +An element that renders when the image hasn't loaded. This means whilst it's loading, or if there was an error. If you notice a flash during loading, you can provide a `delayMs` prop to delay its rendering so it only renders for those with slower connections. For more control, use the `onLoadingStatusChange` handler on `Avatar.Image`. + +## Examples + +### Clickable Avatar with tooltip + +You can compose the Avatar with a [Tooltip](/primitives/docs/components/tooltip) to display extra information. + +```jsx line=1,4,5,7,9-13 +import { Avatar, __Tooltip__ } from "radix-ui"; + +export default () => ( + + + … + + + + Tooltip content + + + +); +``` + +--- + +## Checkbox + +A control that allows the user to toggle between checked and not checked. + +# Checkbox + +A control that allows the user to toggle between checked and not checked. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-checkbox +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Checkbox } from "radix-ui"; + +export default () => ( + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a checkbox. An `input` will also render when used within a `form` to ensure events propagate correctly. + +### Indicator + +Renders when the checkbox is in a checked or indeterminate state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. + +## Examples + +### Indeterminate + +You can set the checkbox to `indeterminate` by taking control of its state. + +```jsx line=5,9-14,16 +import { DividerHorizontalIcon, CheckIcon } from "@radix-ui/react-icons"; +import { Checkbox } from "radix-ui"; + +export default () => { + const [checked, setChecked] = React.useState("indeterminate"); + + return ( + <> + + + {checked === "indeterminate" && } + {checked === true && } + + + + + + ); +}; +``` + +## Accessibility + +Adheres to the [tri-state Checkbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox). + +### Keyboard Interactions + +--- + +## Collapsible + +An interactive component which expands/collapses a panel. + +# Collapsible + +An interactive component which expands/collapses a panel. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-collapsible +``` + +## Anatomy + +Import the components and piece the parts together. + +```jsx +import { Collapsible } from "radix-ui"; + +export default () => ( + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a collapsible. + +### Trigger + +The button that toggles the collapsible. + +### Content + +The component that contains the collapsible content. + +## Examples + +### Animating content size + +Use the `--radix-collapsible-content-width` and/or `--radix-collapsible-content-height` CSS variables to animate the size of the content when it opens/closes. Here's a demo: + +```jsx line=8 +// index.jsx +import { Collapsible } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + … + + +); +``` + +```css line=17,23 +/* styles.css */ +.CollapsibleContent { + overflow: hidden; +} +.CollapsibleContent[data-state="open"] { + animation: slideDown 300ms ease-out; +} +.CollapsibleContent[data-state="closed"] { + animation: slideUp 300ms ease-out; +} + +@keyframes slideDown { + from { + height: 0; + } + to { + height: var(__--radix-collapsible-content-height__); + } +} + +@keyframes slideUp { + from { + height: var(__--radix-collapsible-content-height__); + } + to { + height: 0; + } +} +``` + +## Accessibility + +Adheres to the [Disclosure WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure). + +### Keyboard Interactions + +--- + +## Context Menu + +Displays a menu located at the pointer, triggered by a right click or a long press. + +# Context Menu + +Displays a menu located at the pointer, triggered by a right click or a long +press. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-context-menu +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { ContextMenu } from "radix-ui"; + +export default () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +); +``` + +## API Reference + +Adheres to the [Menu WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu) and uses [roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/menu-button/menu-button-actions.html) to manage focus movement among menu items. + +### Root + +Contains all the parts of a context menu. + +### Trigger + +The area that opens the context menu. Wrap it around the target you want the context menu to open from when right-clicking (or using the relevant keyboard shortcuts). + +### Portal + +When used, portals the content part into the `body`. + +### Content + +The component that pops out in an open context menu. + +### Arrow + +An optional arrow element to render alongside a submenu. This can be used to help visually link the trigger item with the `ContextMenu.Content`. Must be rendered inside `ContextMenu.Content`. + +### Item + +The component that contains the context menu items. + +### Group + +Used to group multiple `ContextMenu.Item`s. + +### Label + +Used to render a label. It won't be focusable using arrow keys. + +### CheckboxItem + +An item that can be controlled and rendered like a checkbox. + +### RadioGroup + +Used to group multiple `ContextMenu.RadioItem`s. + +### RadioItem + +An item that can be controlled and rendered like a radio. + +### ItemIndicator + +Renders when the parent `ContextMenu.CheckboxItem` or `ContextMenu.RadioItem` is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. + +### Separator + +Used to visually separate items in the context menu. + +### Sub + +Contains all the parts of a submenu. + +### SubTrigger + +An item that opens a submenu. Must be rendered inside `ContextMenu.Sub`. + +### SubContent + +The component that pops out when a submenu is open. Must be rendered inside `ContextMenu.Sub`. + +## Examples + +### With submenus + +You can create submenus by using `ContextMenu.Sub` in combination with its parts. + +```jsx line=8-17 + + … + + + … + … + + + Sub menu → + + + Sub menu item + Sub menu item + + + + + + … + + + +``` + +### With disabled items + +You can add special styles to disabled items via the `data-disabled` attribute. + +```jsx line=10 +// index.jsx +import { ContextMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + + … + + … + + + +); +``` + +```css line=2 +/* styles.css */ +.ContextMenuItem[__data-disabled__] { + color: gainsboro; +} +``` + +### With separators + +Use the `Separator` part to add a separator between items. + +```jsx line=6,8 + + … + + + … + + … + + … + + + +``` + +### With labels + +Use the `Label` part to help label a section. + +```jsx line=5 + + … + + + Label + … + … + … + + + +``` + +### With checkbox items + +Use the `CheckboxItem` part to add an item that can be checked. + +```jsx line=6,16-21 +import * as React from "react"; +import { CheckIcon } from "@radix-ui/react-icons"; +import { ContextMenu } from "radix-ui"; + +export default () => { + const [checked, setChecked] = React.useState(true); + + return ( + + … + + + … + … + + + + + + Checkbox item + + + + + ); +}; +``` + +### With radio items + +Use the `RadioGroup` and `RadioItem` parts to add an item that can be checked amongst others. + +```jsx line=6,13-32 +import * as React from "react"; +import { CheckIcon } from "@radix-ui/react-icons"; +import { ContextMenu } from "radix-ui"; + +export default () => { + const [color, setColor] = React.useState("blue"); + + return ( + + … + + + + + + + + Red + + + + + + Blue + + + + + + Green + + + + + + ); +}; +``` + +### With complex items + +You can add extra decorative elements in the `Item` parts, such as images. + +```jsx line=9,13 +import { ContextMenu } from "radix-ui"; + +export default () => ( + + … + + + + + Adolfo Hess + + + + Miyah Myles + + + + +); +``` + +### Constrain the content/sub-content size + +You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport. + +We expose several CSS custom properties such as `--radix-context-menu-trigger-width` and `--radix-context-menu-content-available-height` to support this. Use them to constrain the content dimensions. + +```jsx line=9 +// index.jsx +import { ContextMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css +/* styles.css */ +.ContextMenuContent { + width: var(__--radix-context-menu-trigger-width__); + max-height: var(__--radix-context-menu-content-available-height__); +} +``` + +### Origin-aware animations + +We expose a CSS custom property `--radix-context-menu-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. + +```jsx line=9 +// index.jsx +import { ContextMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css line=3 +/* styles.css */ +.ContextMenuContent { + transform-origin: var(__--radix-context-menu-content-transform-origin__); + animation: scaleIn 0.5s ease-out; +} + +@keyframes scaleIn { + from { + opacity: 0; + transform: scale(0); + } + to { + opacity: 1; + transform: scale(1); + } +} +``` + +### Collision-aware animations + +We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. + +```jsx line=9 +// index.jsx +import { ContextMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css line=6-11 +/* styles.css */ +.ContextMenuContent { + animation-duration: 0.6s; + animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); +} +.ContextMenuContent[__data-side="top"__] { + animation-name: slideUp; +} +.ContextMenuContent[__data-side="bottom"__] { + animation-name: slideDown; +} + +@keyframes slideUp { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +@keyframes slideDown { + from { + opacity: 0; + transform: translateY(-10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} +``` + +## Accessibility + +Uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex) to manage focus movement among menu items. + +### Keyboard Interactions + +--- + +## Dialog + +A window overlaid on either the primary window or another dialog window, rendering the content underneath inert. + +# Dialog + +A window overlaid on either the primary window or another dialog window, +rendering the content underneath inert. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-dialog +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Dialog } from "radix-ui"; + +export default () => ( + + + + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a dialog. + +### Trigger + +The button that opens the dialog. + +### Portal + +When used, portals your overlay and content parts into the `body`. + +### Overlay + +A layer that covers the inert portion of the view when the dialog is open. + +### Content + +Contains content to be rendered in the open dialog. + +### Close + +The button that closes the dialog. + +### Title + +An accessible title to be announced when the dialog is opened. + +If you want to hide the title, wrap it inside our [Visually Hidden](../utilities/visually-hidden) utility like this ``. + +### Description + +An optional accessible description to be announced when the dialog is opened. + +If you want to hide the description, wrap it inside our [Visually Hidden](../utilities/visually-hidden) utility like this ``. If you want to remove the description entirely, remove this part and pass `aria-describedby={undefined}` to `Dialog.Content`. + +## Examples + +### Close after asynchronous form submission + +Use the controlled props to programmatically close the Dialog after an async operation has completed. + +```jsx line=4,7,10,15,17 +import * as React from "react"; +import { Dialog } from "radix-ui"; + +const wait = () => new Promise((resolve) => setTimeout(resolve, 1000)); + +export default () => { + const [open, setOpen] = React.useState(false); + + return ( + + Open + + + +
{ + wait().then(() => setOpen(false)); + event.preventDefault(); + }} + > + {/** some inputs */} + +
+ + + + ); +}; +``` + +### Scrollable overlay + +Move the content inside the overlay to render a dialog with overflow. + +```jsx +// index.jsx +import { Dialog } from "radix-ui"; +import "./styles.css"; + +export default () => { + return ( + + + + + ... + + + + ); +}; +``` + +```css +/* styles.css */ +.DialogOverlay { + background: rgba(0 0 0 / 0.5); + position: fixed; + top: 0; + left: 0; + right: 0; + bottom: 0; + display: grid; + place-items: center; + overflow-y: auto; +} + +.DialogContent { + min-width: 300px; + background: white; + padding: 30px; + border-radius: 4px; +} +``` + +### Custom portal container + +Customise the element that your dialog portals into. + +```jsx line=5,10,16 +import * as React from "react"; +import { Dialog } from "radix-ui"; + +export default () => { + const [container, setContainer] = React.useState(null); + return ( +
+ + + + + ... + + + +
+
+ ); +}; +``` + +## Accessibility + +Adheres to the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal). + +### Keyboard Interactions + +## Custom APIs + +Create your own API by abstracting the primitive parts into your own component. + +### Abstract the overlay and the close button + +This example abstracts the `Dialog.Overlay` and `Dialog.Close` parts. + +#### Usage + +```jsx +import { Dialog, DialogTrigger, DialogContent } from "./your-dialog"; + +export default () => ( + + Dialog trigger + Dialog Content + +); +``` + +#### Implementation + +```jsx +// your-dialog.jsx +import * as React from "react"; +import { Dialog as DialogPrimitive } from "radix-ui"; +import { Cross1Icon } from "@radix-ui/react-icons"; + +export const DialogContent = React.forwardRef( + ({ children, ...props }, forwardedRef) => ( + + + + {children} + + + + + + ), +); + +export const Dialog = DialogPrimitive.Root; +export const DialogTrigger = DialogPrimitive.Trigger; +``` + +--- + +## Dropdown Menu + +Displays a menu to the user—such as a set of actions or functions—triggered by a button. + +# Dropdown Menu + +Displays a menu to the user—such as a set of actions or functions—triggered by +a button. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-dropdown-menu +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { DropdownMenu } from "radix-ui"; + +export default () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a dropdown menu. + +### Trigger + +The button that toggles the dropdown menu. By default, the `DropdownMenu.Content` will position itself against the trigger. + +### Portal + +When used, portals the content part into the `body`. + +### Content + +The component that pops out when the dropdown menu is open. + +### Arrow + +An optional arrow element to render alongside the dropdown menu. This can be used to help visually link the trigger with the `DropdownMenu.Content`. Must be rendered inside `DropdownMenu.Content`. + +### Item + +The component that contains the dropdown menu items. + +### Group + +Used to group multiple `DropdownMenu.Item`s. + +### Label + +Used to render a label. It won't be focusable using arrow keys. + +### CheckboxItem + +An item that can be controlled and rendered like a checkbox. + +### RadioGroup + +Used to group multiple `DropdownMenu.RadioItem`s. + +### RadioItem + +An item that can be controlled and rendered like a radio. + +### ItemIndicator + +Renders when the parent `DropdownMenu.CheckboxItem` or `DropdownMenu.RadioItem` is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. + +### Separator + +Used to visually separate items in the dropdown menu. + +### Sub + +Contains all the parts of a submenu. + +### SubTrigger + +An item that opens a submenu. Must be rendered inside `DropdownMenu.Sub`. + +### SubContent + +The component that pops out when a submenu is open. Must be rendered inside `DropdownMenu.Sub`. + +## Examples + +### With submenus + +You can create submenus by using `DropdownMenu.Sub` in combination with its parts. + +```jsx line=8-17 + + … + + + … + … + + + Sub menu → + + + Sub menu item + Sub menu item + + + + + + … + + + +``` + +### With disabled items + +You can add special styles to disabled items via the `data-disabled` attribute. + +```jsx line=10 +// index.jsx +import { DropdownMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + + … + + … + + + +); +``` + +```css line=2 +/* styles.css */ +.DropdownMenuItem[__data-disabled__] { + color: gainsboro; +} +``` + +### With separators + +Use the `Separator` part to add a separator between items. + +```jsx line=6,8 + + … + + + … + + … + + … + + + +``` + +### With labels + +Use the `Label` part to help label a section. + +```jsx line=5 + + … + + + Label + … + … + … + + + +``` + +### With checkbox items + +Use the `CheckboxItem` part to add an item that can be checked. + +```jsx line=6,16-21 +import * as React from "react"; +import { CheckIcon } from "@radix-ui/react-icons"; +import { DropdownMenu } from "radix-ui"; + +export default () => { + const [checked, setChecked] = React.useState(true); + + return ( + + … + + + … + … + + + + + + Checkbox item + + + + + ); +}; +``` + +### With radio items + +Use the `RadioGroup` and `RadioItem` parts to add an item that can be checked amongst others. + +```jsx line=6,13-32 +import * as React from "react"; +import { CheckIcon } from "@radix-ui/react-icons"; +import { DropdownMenu } from "radix-ui"; + +export default () => { + const [color, setColor] = React.useState("blue"); + + return ( + + … + + + + + + + + Red + + + + + + Blue + + + + + + Green + + + + + + ); +}; +``` + +### With complex items + +You can add extra decorative elements in the `Item` parts, such as images. + +```jsx line=9,13 +import { DropdownMenu } from "radix-ui"; + +export default () => ( + + … + + + + + Adolfo Hess + + + + Miyah Myles + + + + +); +``` + +### Constrain the content/sub-content size + +You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport. + +We expose several CSS custom properties such as `--radix-dropdown-menu-trigger-width` and `--radix-dropdown-menu-content-available-height` to support this. Use them to constrain the content dimensions. + +```jsx line=9 +// index.jsx +import { DropdownMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css +/* styles.css */ +.DropdownMenuContent { + width: var(__--radix-dropdown-menu-trigger-width__); + max-height: var(__--radix-dropdown-menu-content-available-height__); +} +``` + +### Origin-aware animations + +We expose a CSS custom property `--radix-dropdown-menu-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. + +```jsx line=9 +// index.jsx +import { DropdownMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css line=3 +/* styles.css */ +.DropdownMenuContent { + transform-origin: var(__--radix-dropdown-menu-content-transform-origin__); + animation: scaleIn 0.5s ease-out; +} + +@keyframes scaleIn { + from { + opacity: 0; + transform: scale(0); + } + to { + opacity: 1; + transform: scale(1); + } +} +``` + +### Collision-aware animations + +We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. + +```jsx line=9 +// index.jsx +import { DropdownMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css line=6-11 +/* styles.css */ +.DropdownMenuContent { + animation-duration: 0.6s; + animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); +} +.DropdownMenuContent[__data-side="top"__] { + animation-name: slideUp; +} +.DropdownMenuContent[__data-side="bottom"__] { + animation-name: slideDown; +} + +@keyframes slideUp { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +@keyframes slideDown { + from { + opacity: 0; + transform: translateY(-10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} +``` + +## Accessibility + +Adheres to the [Menu Button WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) and uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex) to manage focus movement among menu items. + +### Keyboard Interactions + +## Custom APIs + +Create your own API by abstracting the primitive parts into your own component. + +### Abstract the arrow and item indicators + +This example abstracts the `DropdownMenu.Arrow` and `DropdownMenu.ItemIndicator` parts. It also wraps implementation details for `CheckboxItem` and `RadioItem`. + +#### Usage + +```jsx +import { + DropdownMenu, + DropdownMenuTrigger, + DropdownMenuContent, + DropdownMenuLabel, + DropdownMenuItem, + DropdownMenuGroup, + DropdownMenuCheckboxItem, + DropdownMenuRadioGroup, + DropdownMenuRadioItem, + DropdownMenuSeparator, +} from "./your-dropdown-menu"; + +export default () => ( + + DropdownMenu trigger + + Item + Label + Group + CheckboxItem + Separator + + RadioItem + RadioItem + + + +); +``` + +#### Implementation + +```jsx +// your-dropdown-menu.jsx +import * as React from "react"; +import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui"; +import { CheckIcon, DividerHorizontalIcon } from "@radix-ui/react-icons"; + +export const DropdownMenu = DropdownMenuPrimitive.Root; +export const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger; + +export const DropdownMenuContent = React.forwardRef( + ({ children, ...props }, forwardedRef) => { + return ( + + + {children} + + + + ); + }, +); + +export const DropdownMenuLabel = DropdownMenuPrimitive.Label; +export const DropdownMenuItem = DropdownMenuPrimitive.Item; +export const DropdownMenuGroup = DropdownMenuPrimitive.Group; + +export const DropdownMenuCheckboxItem = React.forwardRef( + ({ children, ...props }, forwardedRef) => { + return ( + + {children} + + {props.checked === "indeterminate" && } + {props.checked === true && } + + + ); + }, +); + +export const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup; + +export const DropdownMenuRadioItem = React.forwardRef( + ({ children, ...props }, forwardedRef) => { + return ( + + {children} + + + + + ); + }, +); + +export const DropdownMenuSeparator = DropdownMenuPrimitive.Separator; +``` + +--- + +## Form + +Collect information from your users using validation rules. + +# Form + +Collect information from your users using validation rules. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-form +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Form } from "radix-ui"; + +export default () => ( + + + + + + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a form. + +### Field + +The wrapper for a field. It handles id/name and label accessibility automatically. + +### Label + +A label element which is automatically wired when nested inside a `Field` part. + +### Control + +A control element (by default an `input`) which is automatically wired when nested inside a `Field` part. + +### Message + +A validation message which is automatically wired (functionality and accessibility) to a given control when nested inside a `Field` part. It can be used for built-in and custom client-side validation, as well as server-side validation. When used outside a `Field` you must pass a `name` prop matching a field. + +`Form.Message` accepts a `match` prop which is used to determine when the message should show. It matches the native HTML validity state (`ValidityState` on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState)) which validates against attributes such as `required`, `min`, `max`. The message will show if the given `match` is `true` on the control’s validity state. + +You can also pass a function to `match` to provide custom validation rules. + +### ValidityState + +Use this render-prop component to access a given field’s validity state in render (see `ValidityState` on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState)). A field's validity is available automatically when nested inside a `Field` part, otherwise you must pass a `name` prop to associate it. + +### Submit + +The submit button. + +## Examples + +### Composing with your own components + +Using `asChild` you can compose the `Form` primitive parts with your own components. + +```jsx line=3 + + Full name + + + + +``` + +It can also be used to compose other types of controls, such as a `select`: + +```jsx line=3 + + Country + + + + +``` + +> Note: At the moment, it is not possible to compose `Form` with Radix's other form primitives such as `Checkbox`, `Select`, etc. We are working on a solution for this. + +### Providing your own validation messages + +When no `children` are provided, `Form.Message` will render a default error message for the given `match`. + +```jsx +// will yield "This value is missing" + +``` + +You can provide a more meaningful message by passing your own `children`. This is also useful for internationalization. + +```jsx +// will yield "Please provide a name" +__Please provide a name__ +``` + +### Custom validation + +On top of all the built-in client-side validation matches described above you can also provide your own custom validation whilst still making use of the platform's validation abilities. It uses the `customError` type present in the [constraint validition API](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation). + +You can pass your own validation function into the `match` prop on `Form.Message`. Here's an example: + +```jsx line=4 + + Full name + + value !== "John"}> + Only John is allowed. + + +``` + +> `match` will be called with the current value of the control as first argument and the entire `FormData` as second argument. +> `match` can also be an `async` function (or return a promise) to perform async validation. + +### Styling based on validity + +We add `data-valid` and `data-invalid` attributes to the relevant parts. Use it to style your components accordingly. +Here is an example styling the `Label` part. + +```jsx line=8 +//index.jsx +import * as React from "react"; +import { Form } from "radix-ui"; + +export default () => ( + + + Email + + + +); +``` + +```css line=2,5 +/* styles.css */ +.FormLabel[__data-invalid__] { + color: red; +} +.FormLabel[__data-valid__] { + color: green; +} +``` + +### Accessing the validity state for more control + +You may need to access the raw validity state of a field in order to display your own icons, or interface with a component library via it's defined props. You can do this by using the `Form.ValidityState` part: + +```jsx line=3-4,7-8 + + Full name + + {(validity) => ( + + + + )} + + +``` + +### Server-side validation + +The component also supports server-side validation using the same `Form.Message` component. +You can re-use the same messages you defined for client-side errors by passing a `forceMatch` prop which will force the message to show regardless of the client-side matching logic. + +If the message doesn't exist on the client-side, you can render a `Form.Message` without a `match` too. +The field is marked as invalid by passing a `serverInvalid` boolean prop to the `Form.Field` part. + +Here's an example with server-side error handling: + +```jsx line=5-8,13,23,28-30,49-54 +import * as React from "react"; +import { Form } from "radix-ui"; + +function Page() { + const [serverErrors, setServerErrors] = React.useState({ + email: false, + password: false, + }); + + return ( + { + const data = Object.fromEntries(new FormData(event.currentTarget)); + + // Submit form data and catch errors in the response + submitForm(data) + .then(() => {}) + /** + * Map errors from your server response into a structure you'd like to work with. + * In this case resulting in this object: `{ email: false, password: true }` + */ + .catch((errors) => __setServerErrors__(mapServerErrors(errors))); + + // prevent default form submission + event.preventDefault(); + }} + onClearServerErrors={() => + __setServerErrors__({ email: false, password: false }) + } + > + + Email address + + + Please enter your email. + + + Please provide a valid email. + + + + + Password + + + Please enter a password. + + {serverErrors.password && ( + + Please provide a valid password. It should contain at least 1 number + and 1 special character. + + )} + + + Submit + + ); +} +``` + +You should clear the server errors using the `onClearServerErrors` callback prop on the `Form.Root` part. It will clear the server errors before the form is re-submitted, and when the form is reset. + +In addition, this provides control over when to reset single server errors. For example you could reset the email server error as soon as the user edits it: + +```jsx line=3 + + Email address + setServerErrors((prev) => ({ ...prev, email: false }))} + /> + Please enter your email. + + Please provide a valid email. + + +``` + +## Accessibility + +The component follows the "inline errors" pattern for validation: + +- Label and control are associated using the `name` provided on `Form.Field` +- When one or more client-side error messages display, they are automatically associated with their matching control and announced accordingly +- Focus is moved to the first invalid control + +--- + +## Hover Card + +For sighted users to preview content available behind a link. + +# Hover Card + +For sighted users to preview content available behind a link. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-hover-card +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { HoverCard } from "radix-ui"; + +export default () => ( + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a hover card. + +### Trigger + +The link that opens the hover card when hovered. + +### Portal + +When used, portals the content part into the `body`. + +### Content + +The component that pops out when the hover card is open. + +### Arrow + +An optional arrow element to render alongside the hover card. This can be used to help visually link the trigger with the `HoverCard.Content`. Must be rendered inside `HoverCard.Content`. + +## Examples + +### Show instantly + +Use the `openDelay` prop to control the time it takes for the hover card to open. + +```jsx line=4 +import { HoverCard } from "radix-ui"; + +export default () => ( + + … + … + +); +``` + +### Constrain the content size + +You may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport. + +We expose several CSS custom properties such as `--radix-hover-card-trigger-width` and `--radix-hover-card-content-available-height` to support this. Use them to constrain the content dimensions. + +```jsx line=9 +// index.jsx +import { HoverCard } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css +/* styles.css */ +.HoverCardContent { + width: var(__--radix-hover-card-trigger-width__); + max-height: var(__--radix-hover-card-content-available-height__); +} +``` + +### Origin-aware animations + +We expose a CSS custom property `--radix-hover-card-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. + +```jsx line=8 +// index.jsx +import { HoverCard } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + … + +); +``` + +```css line=3 +/* styles.css */ +.HoverCardContent { + transform-origin: var(__--radix-hover-card-content-transform-origin__); + animation: scaleIn 0.5s ease-out; +} + +@keyframes scaleIn { + from { + opacity: 0; + transform: scale(0); + } + to { + opacity: 1; + transform: scale(1); + } +} +``` + +### Collision-aware animations + +We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. + +```jsx line=8 +// index.jsx +import { HoverCard } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + … + +); +``` + +```css line=6-11 +/* styles.css */ +.HoverCardContent { + animation-duration: 0.6s; + animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); +} +.HoverCardContent[__data-side="top"__] { + animation-name: slideUp; +} +.HoverCardContent[__data-side="bottom"__] { + animation-name: slideDown; +} + +@keyframes slideUp { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +@keyframes slideDown { + from { + opacity: 0; + transform: translateY(-10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} +``` + +## Accessibility + +The hover card is intended for sighted users only, the content will be inaccessible to keyboard users. + +### Keyboard Interactions + +--- + +## Label + +Renders an accessible label associated with controls. + +# Label + +Renders an accessible label associated with controls. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-label +``` + +## Anatomy + +Import the component. + +```jsx +import { Label } from "radix-ui"; + +export default () => ; +``` + +## API Reference + +### Root + +Contains the content for the label. + +## Accessibility + +This component is based on the native `label` element, it will automatically apply the correct labelling when wrapping controls or using the `htmlFor` attribute. For your own custom controls to work correctly, ensure they use native elements such as `button` or `input` as a base. + +--- + +## Menubar + +A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands. + +# Menu Bar + +A visually persistent menu common in desktop applications that provides quick +access to a consistent set of commands. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-menubar +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Menubar } from "radix-ui"; + +export default () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a menubar. + +### Menu + +A top level menu item, contains a trigger with content combination. + +### Trigger + +The button that toggles the content. By default, the `Menubar.Content` will position itself against the trigger. + +### Portal + +When used, portals the content part into the `body`. + +### Content + +The component that pops out when a menu is open. + +### Arrow + +An optional arrow element to render alongside a menubar menu. This can be used to help visually link the trigger with the `Menubar.Content`. Must be rendered inside `Menubar.Content`. + +### Item + +The component that contains the menubar items. + +### Group + +Used to group multiple `Menubar.Item`s. + +### Label + +Used to render a label. It won't be focusable using arrow keys. + +### CheckboxItem + +An item that can be controlled and rendered like a checkbox. + +### RadioGroup + +Used to group multiple `Menubar.RadioItem`s. + +### RadioItem + +An item that can be controlled and rendered like a radio. + +### ItemIndicator + +Renders when the parent `Menubar.CheckboxItem` or `Menubar.RadioItem` is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. + +### Separator + +Used to visually separate items in a menubar menu. + +### Sub + +Contains all the parts of a submenu. + +### SubTrigger + +An item that opens a submenu. Must be rendered inside `Menubar.Sub`. + +### SubContent + +The component that pops out when a submenu is open. Must be rendered inside `Menubar.Sub`. + +## Examples + +### With submenus + +You can create submenus by using `Menubar.Sub` in combination with its parts. + +```jsx line=9-18 + + + … + + + … + … + + + Sub menu → + + + Sub menu item + Sub menu item + + + + + + … + + + + +``` + +### With disabled items + +You can add special styles to disabled items via the `data-disabled` attribute. + +```jsx line=11 +// index.jsx +import { Menubar } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + + … + + + + … + + … + + + + +); +``` + +```css line=2 +/* styles.css */ +.MenubarItem[__data-disabled__] { + color: gainsboro; +} +``` + +### With separators + +Use the `Separator` part to add a separator between items. + +```jsx line=7,9 + + + … + + + … + + … + + … + + + + +``` + +### With labels + +Use the `Label` part to help label a section. + +```jsx line=6 + + + … + + + Label + … + … + … + + + + +``` + +### With checkbox items + +Use the `CheckboxItem` part to add an item that can be checked. + +```jsx line=6,17-22 +import * as React from "react"; +import { CheckIcon } from "@radix-ui/react-icons"; +import { Menubar } from "radix-ui"; + +export default () => { + const [checked, setChecked] = React.useState(true); + + return ( + + + … + + + … + … + + + + + + Checkbox item + + + + + + ); +}; +``` + +### With radio items + +Use the `RadioGroup` and `RadioItem` parts to add an item that can be checked amongst others. + +```jsx line=6,14-27 +import * as React from "react"; +import { CheckIcon } from "@radix-ui/react-icons"; +import { Menubar } from "radix-ui"; + +export default () => { + const [color, setColor] = React.useState("blue"); + + return ( + + + … + + + + + + + + Red + + + + + + Blue + + + + + + + ); +}; +``` + +### With complex items + +You can add extra decorative elements in the `Item` parts, such as images. + +```jsx line=10,14 +import { Menubar } from "radix-ui"; + +export default () => ( + + + … + + + + + Adolfo Hess + + + + Miyah Myles + + + + + +); +``` + +### Constrain the content/sub-content size + +You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport. + +We expose several CSS custom properties such as `--radix-menubar-trigger-width` and `--radix-menubar-content-available-height` to support this. Use them to constrain the content dimensions. + +```jsx line=9 +// index.jsx +import { Menubar } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css +/* styles.css */ +.MenubarContent { + width: var(__--radix-menubar-trigger-width__); + max-height: var(__--radix-menubar-content-available-height__); +} +``` + +### Origin-aware animations + +We expose a CSS custom property `--radix-menubar-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. + +```jsx line=10 +// index.jsx +import { Menubar } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + + … + + … + + + +); +``` + +```css line=3 +/* styles.css */ +.MenubarContent { + transform-origin: var(__--radix-menubar-content-transform-origin__); + animation: scaleIn 0.5s ease-out; +} + +@keyframes scaleIn { + from { + opacity: 0; + transform: scale(0); + } + to { + opacity: 1; + transform: scale(1); + } +} +``` + +### Collision-aware animations + +We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. + +```jsx line=10 +// index.jsx +import { Menubar } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + + … + + … + + + +); +``` + +```css line=6-11 +/* styles.css */ +.MenubarContent { + animation-duration: 0.6s; + animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); +} +.MenubarContent[__data-side="top"__] { + animation-name: slideUp; +} +.MenubarContent[__data-side="bottom"__] { + animation-name: slideDown; +} + +@keyframes slideUp { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +@keyframes slideDown { + from { + opacity: 0; + transform: translateY(-10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} +``` + +## Accessibility + +Adheres to the [Menu Button WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) and uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex) to manage focus movement among menu items. + +### Keyboard Interactions + +--- + +## Navigation Menu + +A collection of links for navigating websites. + +# Navigation Menu + +A collection of links for navigating websites. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-navigation-menu +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { NavigationMenu } from "radix-ui"; + +export default () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a navigation menu. + +### Sub + +Signifies a submenu. Use it in place of the root part when nested to create a submenu. + +### List + +Contains the top level menu items. + +### Item + +A top level menu item, contains a link or trigger with content combination. + +### Trigger + +The button that toggles the content. + +### Content + +Contains the content associated with each trigger. + +### Link + +A navigational link. + +### Indicator + +An optional indicator element that renders below the list, is used to highlight the currently active trigger. + +### Viewport + +An optional viewport element that is used to render active content outside of the list. + +## Examples + +### Vertical + +You can create a vertical menu by using the `orientation` prop. + +```jsx line=1 + + + + Item one + Item one content + + + Item two + Item Two content + + + +``` + +### Flexible layouts + +Use the `Viewport` part when you need extra control over where `Content` is rendered. This can be helpful when your design +requires an adjusted DOM structure or if you need flexibility to achieve [advanced animation](/primitives/docs/components/navigation-menu#advanced-animation). +Tab focus will be maintained automatically. + +```jsx line=14 + + + + Item one + Item one content + + + Item two + Item two content + + + + {/* NavigationMenu.Content will be rendered here when active */} + + +``` + +### With indicator + +You can use the optional `Indicator` part to highlight the currently active `Trigger`, this is useful when you want to provide +an animated visual cue such as an arrow or highlight to accompany the `Viewport`. + +```jsx line=17 +// index.jsx +import { NavigationMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + + + Item one + Item one content + + + Item two + Item two content + + + + + + + +); +``` + +```css +/* styles.css */ +.NavigationMenuIndicator { + background-color: grey; +} +.NavigationMenuIndicator[data-orientation="horizontal"] { + height: 3px; + transition: + width, + transform, + 250ms ease; +} +``` + +### With submenus + +Create a submenu by nesting your `NavigationMenu` and using the `Sub` part in place of its `Root`. +Submenus work differently to `Root` navigation menus and are similar to [`Tabs`](/primitives/docs/components/tabs) in that one item should always be active, so be +sure to assign and set a `defaultValue`. + +```jsx line=10,25 + + + + Item one + Item one content + + + Item two + + + + + Sub item one + + Sub item one content + + + + Sub item two + + Sub item two content + + + + + + + + +``` + +### With client side routing + +If you need to use the `Link` component provided by your routing package then we recommend composing with `NavigationMenu.Link` via a custom component. +This will ensure accessibility and consistent keyboard control is maintained. Here's an example using Next.js: + +```jsx line=7-16,22,25 +// index.jsx +import { usePathname } from "next/navigation"; +import NextLink from "next/link"; +import { NavigationMenu } from "radix-ui"; +import "./styles.css"; + +const Link = ({ href, ...props }) => { + const pathname = usePathname(); + const isActive = href === pathname; + + return ( + + + + ); +}; + +export default () => ( + + + + Home + + + About + + + +); +``` + +```css +/* styles.css */ +.NavigationMenuLink { + text-decoration: none; +} +.NavigationMenuLink[data-active] { + text-decoration: "underline"; +} +``` + +### Advanced animation + +We expose `--radix-navigation-menu-viewport-[width|height]` and `data-motion['from-start'|'to-start'|'from-end'|'to-end']` attributes +to allow you to animate `Viewport` size and `Content` position based on the enter/exit direction. + +Combining these with `position: absolute;` allows you to create smooth overlapping animation effects when moving between items. + +```jsx line=10-12,16-18,22 +// index.jsx +import { NavigationMenu } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + + + Item one + + Item one content + + + + Item two + + Item two content + + + + + + +); +``` + +```css line=9-20,24,25 +/* styles.css */ +.NavigationMenuContent { + position: absolute; + top: 0; + left: 0; + animation-duration: 250ms; + animation-timing-function: ease; +} +.NavigationMenuContent[__data-motion__="from-start"] { + animation-name: enterFromLeft; +} +.NavigationMenuContent[__data-motion__="from-end"] { + animation-name: enterFromRight; +} +.NavigationMenuContent[__data-motion__="to-start"] { + animation-name: exitToLeft; +} +.NavigationMenuContent[__data-motion__="to-end"] { + animation-name: exitToRight; +} + +.NavigationMenuViewport { + position: relative; + width: var(__--radix-navigation-menu-viewport-width__); + height: var(__--radix-navigation-menu-viewport-height__); + transition: + width, + height, + 250ms ease; +} + +@keyframes enterFromRight { + from { + opacity: 0; + transform: translateX(200px); + } + to { + opacity: 1; + transform: translateX(0); + } +} + +@keyframes enterFromLeft { + from { + opacity: 0; + transform: translateX(-200px); + } + to { + opacity: 1; + transform: translateX(0); + } +} + +@keyframes exitToRight { + from { + opacity: 1; + transform: translateX(0); + } + to { + opacity: 0; + transform: translateX(200px); + } +} + +@keyframes exitToLeft { + from { + opacity: 1; + transform: translateX(0); + } + to { + opacity: 0; + transform: translateX(-200px); + } +} +``` + +## Accessibility + +Adheres to the [`navigation` role requirements](https://www.w3.org/TR/wai-aria-1.2/#navigation). + +### Differences to menubar + +`NavigationMenu` should not be confused with `menubar`, although this primitive shares the name `menu` in the colloquial sense to refer to a set of navigation links, it does not use the WAI-ARIA `menu` role. +This is because `menu` and `menubars` behave like native operating system menus most commonly found in desktop application windows, as such they feature complex functionality like composite focus management and first-character navigation. + +These features are often considered [unnecessary for website navigation](https://github.com/w3c/aria-practices/issues/353) and at worst can confuse users who are familiar with established website patterns. + +See the W3C [Disclosure Navigation Menu](https://w3c.github.io/aria-practices/examples/disclosure/disclosure-navigation.html) example for more information. + +### Link usage and aria-current + +It's important to use `NavigationMenu.Link` for all navigational links within a menu, this not only applies to the main list +but also within any content rendered via `NavigationMenu.Content`. This will ensure consistent keyboard interactions and accessibility +while also giving access to the `active` prop for setting `aria-current` and the active styles. +See [this example](/primitives/docs/components/navigation-menu#with-client-side-routing) for more information on usage with third party routing components. + +### Keyboard Interactions + +--- + +## One-Time Password Field + +A group of single-character text inputs to handle one-time password verification + +# One-Time Password Field + +A group of single-character text inputs to handle one-time password +verification. + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { unstable_OneTimePasswordField as OneTimePasswordField } from "radix-ui"; + +export default () => ( + + {/* one Input for each character of the value */} + + {/* single HiddenInput to store the full value */} + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a one-time password field. + +### Input + +Renders a text input representing a single character in the value. + +### HiddenInput + +## Examples + +### Basic usage + +```jsx +// This will render a field with 6 inputs, for use with +// 6-character passwords. Render an Input component for +// each character of accepted password's length. + + + + + + + + + +``` + +### Segmented controls + +The `Root` component accepts arbitrary children, so rendering a visually segmented list is as simple as rendering separators between inputs. We recommend hiding decorative elements from assistive tech with `aria-hidden` and avoid rendering other meaningful content within `Root` since each child element is expected to belong to the parent with the `group` role. + +```jsx line=3,5,7 + + + + + + + + + + +``` + +### Auto-submit form when password is entered + +Use the `autoSubmit` prop to submit an associated form when all inputs are filled. + +```jsx +function Verify({ validCode }) { + const PASSWORD_LENGTH = 6; + function handleSubmit(event) { + event.preventDefault(); + const formData = event.formData; + if (formData.get("otp") === validCode) { + redirect("/authenticated"); + } else { + window.alert("Invalid code"); + } + } + return ( +
+ + {PASSWORD_LENGTH.map((_, i) => ( + + ))} + {/* HiddenInput is required for the form to have data associated with the field */} + + + +
+ ); +} +``` + +### Controlled value + +```jsx +function Verify({ validCode }) { + const [value, setValue] = React.useState(""); + const PASSWORD_LENGTH = 6; + function handleSubmit() { + if (value === validCode) { + redirect("/authenticated"); + } else { + window.alert("Invalid code"); + } + } + return ( + + {PASSWORD_LENGTH.map((_, i) => ( + + ))} + + ); +} +``` + +## Accessibility + +At the time of writing, there is no singular established pattern in WCAG guidelines for implementing one-time password fields as separate inputs. The behavior aims to get as close as possible to having the field act as a single input, with a few exceptions to match user expectations based on our initial research, testing, and gathering feedback. + +This component is implemented as `input` elements within a container with a role of `group` to indicate that child inputs are related. Inputs can be navigated and focused using direction keys, and typing input will move focus to the next input until the last input is reached. + +Pasting a value into the field will replace the contents of all inputs, regardless of the currently focused input. Based on our research this seems to align with most user expectations, where values are often pasted from password-managers or an email. + +### Keyboard Interactions + +--- + +## Password Toggle Field + +A password input field with an integrated button to toggle the value's visibility + +# Password Toggle Field + +A password input field with an integrated button to toggle the value's +visibility. + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { unstable_PasswordToggleField as PasswordToggleField } from "radix-ui"; +import { EyeClosedIcon, EyeOpenIcon } from "@radix-ui/react-icons"; + +export default () => ( + + + + } + hidden={} + /> + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a password toggle field. + +### Input + +Renders a the input containing the password value. + +### Toggle + +### Slot + +### Icon + +## Examples + +### Basic usage + +```jsx + + + + } + hidden={} + /> + + +``` + +### With `Slot` + +```jsx + + + + + +``` + +### With `Slot` + `render` prop + +```jsx + + + + ( + + + + )} + /> + + +``` + +--- + +## Popover + +Displays rich content in a portal, triggered by a button. + +# Popover + +Displays rich content in a portal, triggered by a button. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-popover +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Popover } from "radix-ui"; + +export default () => ( + + + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a popover. + +### Trigger + +The button that toggles the popover. By default, the `Popover.Content` will position itself against the trigger. + +### Anchor + +An optional element to position the `Popover.Content` against. If this part is not used, the content will position alongside the . + +### Portal + +When used, portals the content part into the `body`. + +### Content + +The component that pops out when the popover is open. + +### Arrow + +An optional arrow element to render alongside the popover. This can be used to help visually link the anchor with the `Popover.Content`. Must be rendered inside `Popover.Content`. + +### Close + +The button that closes an open popover. + +## Examples + +### Constrain the content size + +You may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport. + +We expose several CSS custom properties such as `--radix-popover-trigger-width` and `--radix-popover-content-available-height` to support this. Use them to constrain the content dimensions. + +```jsx line=9 +// index.jsx +import { Popover } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css +/* styles.css */ +.PopoverContent { + width: var(__--radix-popover-trigger-width__); + max-height: var(__--radix-popover-content-available-height__); +} +``` + +### Origin-aware animations + +We expose a CSS custom property `--radix-popover-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. + +```jsx line=9 +// index.jsx +import { Popover } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + … + + +); +``` + +```css line=3 +/* styles.css */ +.PopoverContent { + transform-origin: var(__--radix-popover-content-transform-origin__); + animation: scaleIn 0.5s ease-out; +} + +@keyframes scaleIn { + from { + opacity: 0; + transform: scale(0); + } + to { + opacity: 1; + transform: scale(1); + } +} +``` + +### Collision-aware animations + +We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. + +```jsx line=9 +// index.jsx +import { Popover } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + … + + +); +``` + +```css line=6-11 +/* styles.css */ +.PopoverContent { + animation-duration: 0.6s; + animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); +} +.PopoverContent[__data-side__="top"] { + animation-name: slideUp; +} +.PopoverContent[__data-side__="bottom"] { + animation-name: slideDown; +} + +@keyframes slideDown { + from { + opacity: 0; + transform: translateY(-10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +@keyframes slideUp { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} +``` + +### With custom anchor + +You can anchor the content to another element if you do not want to use the trigger as the anchor. + +```jsx line=7-11 +// index.jsx +import { Popover } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + +
+ Row as anchor Trigger +
+ + + + … + + +); +``` + +```css +/* styles.css */ +.Row { + background-color: gainsboro; + padding: 20px; +} +``` + +## Accessibility + +Adheres to the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal). + +### Keyboard Interactions + +## Custom APIs + +Create your own API by abstracting the primitive parts into your own component. + +#### Abstract the arrow and set default configuration + +This example abstracts the `Popover.Arrow` part and sets a default `sideOffset` configuration. + +#### Usage + +```jsx +import { Popover, PopoverTrigger, PopoverContent } from "./your-popover"; + +export default () => ( + + Popover trigger + Popover content + +); +``` + +#### Implementation + +```jsx +// your-popover.jsx +import * as React from "react"; +import { Popover as PopoverPrimitive } from "radix-ui"; + +export const Popover = PopoverPrimitive.Root; +export const PopoverTrigger = PopoverPrimitive.Trigger; + +export const PopoverContent = React.forwardRef( + ({ children, ...props }, forwardedRef) => ( + + + {children} + + + + ), +); +``` + +--- + +## Progress + +Displays an indicator showing the completion progress of a task, typically displayed as a progress bar. + +# Progress + +Displays an indicator showing the completion progress of a task, typically +displayed as a progress bar. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-progress +``` + +### Anatomy + +Import all parts and piece them together. + +```jsx +import { Progress } from "radix-ui"; + +export default () => ( + + + +); +``` + +## Accessibility + +Adheres to the [`progressbar` role requirements](https://www.w3.org/WAI/ARIA/apg/patterns/meter). + +## API Reference + +### Root + +Contains all of the progress parts. + +### Indicator + +Used to show the progress visually. It also makes progress accessible to assistive technologies. + +--- + +## Radio Group + +A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time. + +# Radio Group + +A set of checkable buttons—known as radio buttons—where no more than one of +the buttons can be checked at a time. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-radio-group +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { RadioGroup } from "radix-ui"; + +export default () => ( + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a radio group. + +### Item + +An item in the group that can be checked. An `input` will also render when used within a `form` to ensure events propagate correctly. + +### Indicator + +Renders when the radio item is in a checked state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. + +## Accessibility + +Adheres to the [Radio Group WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio) and uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/patterns/radio/examples/radio) to manage focus movement among radio items. + +### Keyboard Interactions + +--- + +## Scroll Area + +Augments native scroll functionality for custom, cross-browser styling. + +# Scroll Area + +Augments native scroll functionality for custom, cross-browser styling. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-scroll-area +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { ScrollArea } from "radix-ui"; + +export default () => ( + + + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a scroll area. + +### Viewport + +The viewport area of the scroll area. + +### Scrollbar + +The vertical scrollbar. Add a second `Scrollbar` with an `orientation` prop to enable horizontal scrolling. + +### Thumb + +The thumb to be used in `ScrollArea.Scrollbar`. + +### Corner + +The corner where both vertical and horizontal scrollbars meet. + +## Accessibility + +In most cases, it's best to rely on native scrolling and work with the customization options available in CSS. When that isn't enough, `ScrollArea` provides additional customizability while maintaining the browser's native scroll behavior (as well as accessibility features, like keyboard scrolling). + +### Keyboard Interactions + +Scrolling via keyboard is supported by default because the component relies on native scrolling. Specific keyboard interactions may differ between platforms, so we do not specify them here or add specific event listeners to handle scrolling via key events. + +--- + +## Select + +Displays a list of options for the user to pick from—triggered by a button. + +# Select + +Displays a list of options for the user to pick from—triggered by a button. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-select +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Select } from "radix-ui"; + +export default () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a select. + +### Trigger + +The button that toggles the select. The `Select.Content` will position itself by aligning over the trigger. + +### Value + +The part that reflects the selected value. By default the selected item's text will be rendered. if you require more control, you can instead control the select and pass your own `children`. It should not be styled to ensure correct positioning. An optional `placeholder` prop is also available for when the select has no value. + +### Icon + +A small icon often displayed next to the value as a visual affordance for the fact it can be open. By default renders ▼ but you can use your own icon via `asChild` or use `children`. + +### Portal + +When used, portals the content part into the `body`. + +### Content + +The component that pops out when the select is open. + +### Viewport + +The scrolling viewport that contains all of the items. + +### Item + +The component that contains the select items. + +### ItemText + +The textual part of the item. It should only contain the text you want to see in the trigger when that item is selected. It should not be styled to ensure correct positioning. + +### ItemIndicator + +Renders when the item is selected. You can style this element directly, or you can use it as a wrapper to put an icon into, or both. + +### ScrollUpButton + +An optional button used as an affordance to show the viewport overflow as well as functionaly enable scrolling upwards. + +### ScrollDownButton + +An optional button used as an affordance to show the viewport overflow as well as functionaly enable scrolling downwards. + +### Group + +Used to group multiple items. use in conjunction with `Select.Label` to ensure good accessibility via automatic labelling. + +### Label + +Used to render the label of a group. It won't be focusable using arrow keys. + +### Separator + +Used to visually separate items in the select. + +### Arrow + +An optional arrow element to render alongside the content. This can be used to help visually link the trigger with the `Select.Content`. Must be rendered inside `Select.Content`. Only available when `position` is set to `popper`. + +## Examples + +### Change the positioning mode + +By default, `Select` will behave similarly to a native MacOS menu by positioning `Select.Content` relative to the active item. If you would prefer an alternative positioning approach similar to `Popover` or `DropdownMenu` then you can set `position` to `popper` and make use of additional alignment options such as `side`, `sideOffset` and more. + +```jsx line=8 +// index.jsx +import { Select } from "radix-ui"; + +export default () => ( + + … + + + … + + + +); +``` + +### Constrain the content size + +When using `position="popper"` on `Select.Content`, you may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport. + +We expose several CSS custom properties such as `--radix-select-trigger-width` and `--radix-select-content-available-height` to support this. Use them to constrain the content dimensions. + +```jsx line=9 +// index.jsx +import { Select } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css +/* styles.css */ +.SelectContent { + width: var(__--radix-select-trigger-width__); + max-height: var(__--radix-select-content-available-height__); +} +``` + +### With disabled items + +You can add special styles to disabled items via the `data-disabled` attribute. + +```jsx line=11 +// index.jsx +import { Select } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + + + … + + … + … + + + + +); +``` + +```css line=2 +/* styles.css */ +.SelectItem[__data-disabled__] { + color: "gainsboro"; +} +``` + +### With a placeholder + +You can use the `placeholder` prop on `Value` for when the select has no value. There's also a `data-placeholder` attribute on `Trigger` to help with styling. + +```jsx line=7,8 +// index.jsx +import { Select } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + + + + + + … + + +); +``` + +```css line=2 +/* styles.css */ +.SelectTrigger[__data-placeholder__] { + color: "gainsboro"; +} +``` + +### With separators + +Use the `Separator` part to add a separator between items. + +```jsx line=9 + + … + + + + … + … + … + + … + … + + + + +``` + +### With grouped items + +Use the `Group` and `Label` parts to group items in a section. + +```jsx line=6-7,11 + + … + + + + + Label + … + … + … + + + + + +``` + +### With complex items + +You can use custom content in your items. + +```jsx line=11 +import { Select } from "radix-ui"; + +export default () => ( + + … + + + + + + + Adolfo Hess + + … + + … + … + + + + +); +``` + +### Controlling the value displayed in the trigger + +By default the trigger will automatically display the selected item `ItemText`'s content. You can control what appears by chosing to put things inside/outside the `ItemText` part. + +If you need more flexibility, you can control the component using `value`/`onValueChange` props and passing `children` to `SelectValue`. Remember to make sure what you put in there is accessible. + +```jsx line=1,4,6 +const countries = { france: "🇫🇷", "united-kingdom": "🇬🇧", spain: "🇪🇸" }; + +export default () => { + const [value, setValue] = React.useState("france"); + return ( + + + + {__countries[value]__} + + + + + + + + France + … + + + United Kingdom + … + + + Spain + … + + + + + + ); +}; +``` + +### With custom scrollbar + +The native scrollbar is hidden by default as we recommend using the `ScrollUpButton` and `ScrollDownButton` parts for the best UX. If you do not want to use these parts, compose your select with our [Scroll Area](scroll-area) primitive. + +```jsx line=10,12,18-20 +// index.jsx +import { Select, ScrollArea } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + + + + … + … + … + + + + + + + + + +); +``` + +```css +/* styles.css */ +.ScrollAreaRoot { + width: 100%; + height: 100%; +} + +.ScrollAreaViewport { + width: 100%; + height: 100%; +} + +.ScrollAreaScrollbar { + width: 4px; + padding: 5px 2px; +} + +.ScrollAreaThumb { + background: rgba(0, 0, 0, 0.3); + border-radius: 3px; +} +``` + +## Accessibility + +Adheres to the [ListBox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox). + +See the W3C [Select-Only Combobox](https://www.w3.org/TR/wai-aria-practices/examples/combobox/combobox-select-only.html) example for more information. + +### Keyboard Interactions + +### Labelling + +Use our [Label](label) component in order to offer a visual and accessible label for the select. + +```jsx line=5,8,12 +import { Select, Label } from "radix-ui"; + +export default () => ( + <> + + + {/* or */} + + + + … + + … + + + +); +``` + +## Custom APIs + +Create your own API by abstracting the primitive parts into your own component. + +### Abstract down to `Select` and `SelectItem` + +This example abstracts most of the parts. + +#### Usage + +```jsx +import { Select, SelectItem } from "./your-select"; + +export default () => ( + +); +``` + +#### Implementation + +```jsx +// your-select.jsx +import * as React from "react"; +import { Select as SelectPrimitive } from "radix-ui"; +import { + CheckIcon, + ChevronDownIcon, + ChevronUpIcon, +} from "@radix-ui/react-icons"; + +export const Select = React.forwardRef( + ({ children, ...props }, forwardedRef) => { + return ( + + + + + + + + + + + + + {children} + + + + + + + ); + }, +); + +export const SelectItem = React.forwardRef( + ({ children, ...props }, forwardedRef) => { + return ( + + {children} + + + + + ); + }, +); +``` + +--- + +## Separator + +Visually or semantically separates content. + +# Separator + +Visually or semantically separates content. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-separator +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Separator } from "radix-ui"; + +export default () => ; +``` + +## API Reference + +### Root + +The separator. + +## Accessibility + +Adheres to the [`separator` role requirements](https://www.w3.org/TR/wai-aria-1.2/#separator). + +--- + +## Slider + +An input where the user selects a value from within a given range. + +# Slider + +An input where the user selects a value from within a given range. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-slider +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Slider } from "radix-ui"; + +export default () => ( + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a slider. It will render an `input` for each thumb when used within a `form` to ensure events propagate correctly. + +### Track + +The track that contains the `Slider.Range`. + +### Range + +The range part. Must live inside `Slider.Track`. + +### Thumb + +A draggable thumb. You can render multiple thumbs. + +## Examples + +### Vertical orientation + +Use the `orientation` prop to create a vertical slider. + +```jsx line=6 +// index.jsx +import { Slider } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + + + + + +); +``` + +```css line=7,18,26 +/* styles.css */ +.SliderRoot { + position: relative; + display: flex; + align-items: center; +} +.SliderRoot[__data-orientation="vertical"__] { + flex-direction: column; + width: 20px; + height: 100px; +} + +.SliderTrack { + position: relative; + flex-grow: 1; + background-color: grey; +} +.SliderTrack[__data-orientation="vertical"__] { + width: 3px; +} + +.SliderRange { + position: absolute; + background-color: black; +} +.SliderRange[__data-orientation="vertical"__] { + width: 100%; +} + +.SliderThumb { + display: block; + width: 20px; + height: 20px; + background-color: black; +} +``` + +### Create a range + +Add multiple thumbs and values to create a range slider. + +```jsx line=4,8-9 +import { Slider } from "radix-ui"; + +export default () => ( + + + + + + + +); +``` + +### Define step size + +Use the `step` prop to increase the stepping interval. + +```jsx line=4 +import { Slider } from "radix-ui"; + +export default () => ( + + + + + + +); +``` + +### Prevent thumb overlap + +Use `minStepsBetweenThumbs` to avoid thumbs with equal values. + +```jsx line=4 +import { Slider } from "radix-ui"; + +export default () => ( + + + + + + + +); +``` + +## Accessibility + +Adheres to the [Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb). + +### Keyboard Interactions + +## Custom APIs + +Create your own API by abstracting the primitive parts into your own component. + +### Abstract all parts + +This example abstracts all of the `Slider` parts so it can be used as a self closing element. + +#### Usage + +```jsx +import { Slider } from "./your-slider"; + +export default () => ; +``` + +#### Implementation + +```jsx +// your-slider.jsx +import { Slider as SliderPrimitive } from "radix-ui"; + +export const Slider = React.forwardRef((props, forwardedRef) => { + const value = props.value || props.defaultValue; + + return ( + + + + + {value.map((_, i) => ( + + ))} + + ); +}); +``` + +## Caveats + +### Mouse events are not fired + +Because of [a limitation](https://github.com/radix-ui/primitives/blob/83a8c13bf66f3d9f17d77caeb187a69eb146930b/packages/react/slider/src/Slider.tsx#L383-L384) we faced during implementation, the following example won't work as expected and the `onMouseDown` and `onMouseUp` event handlers won't be fired: + +```jsx + console.log("onMouseDown")} + onMouseUp={() => console.log("onMouseUp")} +> + … + +``` + +We recommend using pointer events instead (eg. `onPointerDown`, `onPointerUp`). Regardless of the above limitation, these events are better suited for cross-platform/device handling as they are fired for all pointer input types (mouse, touch, pen, etc.). + +--- + +## Switch + +A control that allows the user to toggle between checked and not checked. + +# Switch + +A control that allows the user to toggle between checked and not checked. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-switch +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Switch } from "radix-ui"; + +export default () => ( + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a switch. An `input` will also render when used within a `form` to ensure events propagate correctly. + +### Thumb + +The thumb that is used to visually indicate whether the switch is on or off. + +## Accessibility + +Adheres to the [`switch` role requirements](https://www.w3.org/WAI/ARIA/apg/patterns/switch). + +### Keyboard Interactions + +--- + +## Tabs + +A set of layered sections of content—known as tab panels—that are displayed one at a time. + +# Tabs + +A set of layered sections of content—known as tab panels—that are displayed +one at a time. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-tabs +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Tabs } from "radix-ui"; + +export default () => ( + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the tabs component parts. + +### List + +Contains the triggers that are aligned along the edge of the active content. + +### Trigger + +The button that activates its associated content. + +### Content + +Contains the content associated with each trigger. + +## Examples + +### Vertical + +You can create vertical tabs by using the `orientation` prop. + +```jsx line=4 +import { Tabs } from "radix-ui"; + +export default () => ( + + + One + Two + Three + + Tab one content + Tab two content + Tab three content + +); +``` + +## Accessibility + +Adheres to the [Tabs WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs). + +### Keyboard Interactions + +--- + +## Toast + +A succinct message that is displayed temporarily. + +# Toast + +A succinct message that is displayed temporarily. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-toast +``` + +## Anatomy + +Import the component. + +```jsx +import { Toast } from "radix-ui"; + +export default () => ( + + + + + + + + + + +); +``` + +## API Reference + +### Provider + +The provider that wraps your toasts and toast viewport. It usually wraps the application. + +### Viewport + +The fixed area where toasts appear. Users can jump to the viewport by pressing a hotkey. It is up to you to ensure the discoverability of the hotkey for keyboard users. + +### Root + +The toast that automatically closes. It should not be held open to [acquire a user response](/primitives/docs/components/toast#action). + +### Title + +An optional title for the toast. + +### Description + +The toast message. + +### Action + +An action that is safe to ignore to ensure users are not expected to complete tasks with unexpected side effects as a result of a [time limit](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-required-behaviors.html). + +When obtaining a user response is necessary, portal an [`AlertDialog`](/primitives/docs/components/alert-dialog) styled as a toast into the viewport instead. + +### Close + +A button that allows users to dismiss the toast before its duration has elapsed. + +## Examples + +### Custom hotkey + +Override the default hotkey using the `event.code` value for each key from [keycode.info](https://keycode.info/). + +```jsx line=3 + + {/* ... */} + + +``` + +### Custom duration + +Customise the duration of a toast to override the provider value. + +```jsx line=1 + + Saved! + +``` + +### Duplicate toasts + +When a toast must appear every time a user clicks a button, use state to render multiple instances of the same toast (see below). Alternatively, you can abstract the parts to create your own [imperative API](/primitives/docs/components/toast#imperative-api). + +```jsx line=6,11-15 +export default () => { + const [savedCount, setSavedCount] = React.useState(0); + + return ( +
+
setSavedCount((count) => count + 1)}> + {/* ... */} + +
+ + {Array.from({ length: savedCount }).map((_, index) => ( + + Saved! + + ))} +
+ ); +}; +``` + +### Animating swipe gesture + +Combine `--radix-toast-swipe-move-[x|y]` and `--radix-toast-swipe-end-[x|y]` CSS variables with `data-swipe="[start|move|cancel|end]"` attributes to animate a swipe to close gesture. Here's an example: + +```jsx line=6,7 +// index.jsx +import { Toast } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + ... + + +); +``` + +```css line=2,3,5,9,15 +/* styles.css */ +.ToastRoot[__data-swipe__="move"] { + transform: translateX(var(__--radix-toast-swipe-move-x__)); +} +.ToastRoot[__data-swipe__="cancel"] { + transform: translateX(0); + transition: transform 200ms ease-out; +} +.ToastRoot[__data-swipe__="end"] { + animation: slideRight 100ms ease-out; +} + +@keyframes slideRight { + from { + transform: translateX(var(__--radix-toast-swipe-end-x__)); + } + to { + transform: translateX(100%); + } +} +``` + +## Accessibility + +Adheres to the [`aria-live` requirements](https://www.w3.org/TR/wai-aria/#aria-live). + +### Sensitivity + +Control the sensitivity of the toast for screen readers using the `type` prop. + +For toasts that are the result of a user action, choose `foreground`. Toasts generated from background tasks should use `background`. + +#### Foreground + +Foreground toasts are announced immediately. Assistive technologies may choose to clear previously queued messages when a foreground toast appears. Try to avoid stacking distinct foreground toasts at the same time. + +#### Background + +Background toasts are announced at the next graceful opportunity, for example, when the screen reader has finished reading its current sentence. They do not clear queued messages so overusing them can be perceived as a laggy user experience for screen reader users when used in response to a user interaction. + +```jsx line=1,6 + + File removed successfully. + Dismiss + + + + We've just released Radix 1.0. + Dismiss + +``` + +### Alternative action + +Use the `altText` prop on the `Action` to instruct an alternative way of actioning the toast to screen reader users. + +You can direct the user to a permanent place in your application where they can action it or implement your own custom hotkey logic. If implementing the latter, use `foreground` type to announce immediately and increase the duration to give the user ample time. + +```jsx line=4,10,12 + + Upgrade Available! + We've just released Radix 1.0. + + Upgrade + + Dismiss + + + + File removed successfully. + + Undo Alt+U + + Dismiss + +``` + +### Close icon button + +When providing an icon (or font icon), remember to label it correctly for screen reader users. + +```jsx line=3-4 + + Saved! + + × + + +``` + +### Keyboard Interactions + +## Custom APIs + +### Abstract parts + +Create your own API by abstracting the primitive parts into your own component. + +#### Usage + +```jsx +import { Toast } from "./your-toast"; + +export default () => ( + + + +); +``` + +#### Implementation + +```jsx +// your-toast.jsx +import { Toast as ToastPrimitive } from "radix-ui"; + +export const Toast = ({ title, content, children, ...props }) => { + return ( + + {title && {title}} + {content} + {children && ( + {children} + )} + + × + + + ); +}; +``` + +### Imperative API + +Create your own imperative API to allow [toast duplication](/primitives/docs/components/toast#duplicate-toasts) if preferred. + +#### Usage + +```jsx +import { Toast } from "./your-toast"; + +export default () => { + const savedRef = React.useRef(); + return ( +
+
savedRef.current.publish()}> + {/* ... */} + +
+ Saved successfully! +
+ ); +}; +``` + +#### Implementation + +```jsx +// your-toast.jsx +import * as React from "react"; +import { Toast as ToastPrimitive } from "radix-ui"; + +export const Toast = React.forwardRef((props, forwardedRef) => { + const { children, ...toastProps } = props; + const [count, setCount] = React.useState(0); + + React.useImperativeHandle(forwardedRef, () => ({ + publish: () => setCount((count) => count + 1), + })); + + return ( + <> + {Array.from({ length: count }).map((_, index) => ( + + {children} + Dismiss + + ))} + + ); +}); +``` + +--- + +## Toggle Group + +A set of two-state buttons that can be toggled on or off. + +# Toggle Group + +A set of two-state buttons that can be toggled on or off. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-toggle-group +``` + +## Anatomy + +Import the component. + +```jsx +import { ToggleGroup } from "radix-ui"; + +export default () => ( + + + +); +``` + +## API Reference + +### Root + +Contains all the parts of a toggle group. + +### Item + +An item in the group. + +## Examples + +### Ensuring there is always a value + +You can control the component to ensure a value. + +```jsx line=5,8 +import * as React from "react"; +import { ToggleGroup } from "radix-ui"; + +export default () => { + const [value, setValue] = React.useState("left"); + + return ( + { + if (value) setValue(value); + }} + > + + + + + + + + + + + ); +}; +``` + +## Accessibility + +Uses [roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/radio/radio.html) to manage focus movement among items. + +### Keyboard Interactions + +--- + +## Toggle + +A two-state button that can be either on or off. + +# Toggle + +A two-state button that can be either on or off. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-toggle +``` + +## Anatomy + +Import the component. + +```jsx +import { Toggle } from "radix-ui"; + +export default () => ; +``` + +## API Reference + +### Root + +The toggle. + +## Accessibility + +### Keyboard Interactions + +--- + +## Toolbar + +A container for grouping a set of controls, such as buttons, toggle groups or dropdown menus. + +# Toolbar + +A container for grouping a set of controls, such as buttons, toggle groups or +dropdown menus. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-toolbar +``` + +## Anatomy + +Import the component. + +```jsx +import { Toolbar } from "radix-ui"; + +export default () => ( + + + + + + + + +); +``` + +## API Reference + +### Root + +Contains all the toolbar component parts. + +### Button + +A button item. + +### Link + +A link item. + +### ToggleGroup + +A set of two-state buttons that can be toggled on or off. + +### ToggleItem + +An item in the group. + +### Separator + +Used to visually separate items in the toolbar. + +## Examples + +### Use with other primitives + +All our primitives which expose a `Trigger` part, such as `Dialog`, `AlertDialog`, `Popover`, `DropdownMenu` can be composed within a toolbar by using the [`asChild` prop](/primitives/docs/guides/composition). + +Here is an example using our `DropdownMenu` primitive. + +```jsx line=8-10 +import { Toolbar, DropdownMenu } from "radix-ui"; + +export default () => ( + + Action 1 + + + + Trigger + + … + + +); +``` + +## Accessibility + +Uses [roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/radio/radio.html) to manage focus movement among items. + +### Keyboard Interactions + +--- + +## Tooltip + +A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. + +# Tooltip + +A popup that displays information related to an element when the element +receives keyboard focus or the mouse hovers over it. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-tooltip +``` + +## Anatomy + +Import all parts and piece them together. + +```jsx +import { Tooltip } from "radix-ui"; + +export default () => ( + + + + + + + + + + +); +``` + +## API Reference + +### Provider + +Wraps your app to provide global functionality to your tooltips. + +### Root + +Contains all the parts of a tooltip. + +### Trigger + +The button that toggles the tooltip. By default, the `Tooltip.Content` will position itself against the trigger. + +### Portal + +When used, portals the content part into the `body`. + +### Content + +The component that pops out when the tooltip is open. + +### Arrow + +An optional arrow element to render alongside the tooltip. This can be used to help visually link the trigger with the `Tooltip.Content`. Must be rendered inside `Tooltip.Content`. + +## Examples + +### Configure globally + +Use the `Provider` to control `delayDuration` and `skipDelayDuration` globally. + +```jsx line=4 +import { Tooltip } from "radix-ui"; + +export default () => ( + + + … + … + + + … + … + + +); +``` + +### Show instantly + +Use the `delayDuration` prop to control the time it takes for the tooltip to open. + +```jsx line=4 +import { Tooltip } from "radix-ui"; + +export default () => ( + + … + … + +); +``` + +### Constrain the content size + +You may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport. + +We expose several CSS custom properties such as `--radix-tooltip-trigger-width` and `--radix-tooltip-content-available-height` to support this. Use them to constrain the content dimensions. + +```jsx line=9 +// index.jsx +import { Tooltip } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + + + … + + + +); +``` + +```css +/* styles.css */ +.TooltipContent { + width: var(__--radix-tooltip-trigger-width__); + max-height: var(__--radix-tooltip-content-available-height__); +} +``` + +### Origin-aware animations + +We expose a CSS custom property `--radix-tooltip-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions. + +```jsx line=8 +// index.jsx +import { Tooltip } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + … + +); +``` + +```css line=3-4 +/* styles.css */ +.TooltipContent { + transform-origin: var(--radix-tooltip-content-transform-origin); + animation: scaleIn 0.5s ease-out; +} + +@keyframes scaleIn { + from { + opacity: 0; + transform: scale(0); + } + to { + opacity: 1; + transform: scale(1); + } +} +``` + +### Collision-aware animations + +We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations. + +```jsx line=8 +// index.jsx +import { Tooltip } from "radix-ui"; +import "./styles.css"; + +export default () => ( + + … + … + +); +``` + +```css line=6,9 +/* styles.css */ +.TooltipContent { + animation-duration: 0.6s; + animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); +} +.TooltipContent[data-side="top"] { + animation-name: slideUp; +} +.TooltipContent[data-side="bottom"] { + animation-name: slideDown; +} + +@keyframes slideDown { + from { + opacity: 0; + transform: translateY(-10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +@keyframes slideUp { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} +``` + +## Accessibility + +### Keyboard Interactions + +## Custom APIs + +Create your own API by abstracting the primitive parts into your own component. + +### Abstract parts and introduce a content prop + +This example abstracts all of the `Tooltip` parts and introduces a new `content` prop. + +#### Usage + +```jsx +import { Tooltip } from "./your-tooltip"; + +export default () => ( + + + +); +``` + +#### Implementation + +Use the [`asChild` prop](/primitives/docs/guides/composition) to convert the trigger part into a slottable area. It will replace the trigger with the child that gets passed to it. + +```jsx line=8-10 +// your-tooltip.jsx +import * as React from "react"; +import { Tooltip as TooltipPrimitive } from "radix-ui"; + +export function Tooltip({ + children, + content, + open, + defaultOpen, + onOpenChange, + ...props +}) { + return ( + + + {children} + + + {content} + + + + ); +} +``` + +--- + +# Utilities + +## Accessible Icon + +Makes icons accessible by adding a label. + +# Accessible Icon + +Makes icons accessible by adding a label. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-accessible-icon +``` + +## Anatomy + +Import the component. + +```jsx +import { AccessibleIcon } from "radix-ui"; + +export default () => ; +``` + +## API Reference + +### Root + +Contains the icon to make accessible. + +## Accessibility + +Most icons or icon systems come with no accessibility built-in. For example, the same visual **cross** icon may in fact mean **"close"** or **"delete"**. This component lets you give meaning to icons used throughout your app. + +This is built with [Visually Hidden](../utilities/visually-hidden). + +--- + +## Direction Provider + +Wraps your app to provide global reading direction. + +# Direction Provider + +Wraps your app to provide global reading direction. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-direction +``` + +## Anatomy + +Import the component. + +```jsx +import { Direction } from "radix-ui"; + +export default () => ; +``` + +## API Reference + +### Provider + +When creating localized apps that require right-to-left (RTL) reading direction, you need to wrap your application with the `Direction.Provider` component to ensure all of the primitives adjust their behavior based on the `dir` prop. + +## Example + +Use the direction provider. + +```jsx +import { Direction } from "radix-ui"; + +export default () => ( + {/* your app */} +); +``` + +--- + +## Portal + +Renders a React subtree in a different part of the DOM. + +# Portal + +Renders a React subtree in a different part of the DOM. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-portal +``` + +## Anatomy + +Import the component. + +```jsx +import { Portal } from "radix-ui"; + +export default () => ; +``` + +## Basic example + +Use the portal primitive. + +```jsx +import { Portal } from "radix-ui"; + +export default () => Content; +``` + +## API Reference + +### Root + +Anything you put inside this component will be rendered in a separate `
` element. By default, this element will be appended to `document.body` but you can choose a different container by using the `container` prop. + +--- + +## Slot + +Merges its props onto its immediate child. + +# Slot + +Merges its props onto its immediate child. + +## Installation + +Install the component from your command line. + +```bash +npm install @radix-ui/react-slot +``` + +## Anatomy + +Import the component. + +```jsx +import { Slot } from "radix-ui"; + +export default () => ( + +
Hello
+ +); +``` + +## Basic example + +Use to create your own `asChild` API. + +When your component has a single children element: + +```jsx line=9 +// your-button.jsx +import * as React from "react"; +import { Slot } from "radix-ui"; + +function Button({ asChild, ...props }) { + const Comp = asChild ? Slot.Root : "button"; + return ; +} +``` + +Use `Slottable` when your component has multiple children to pass the props to the correct element: + +```jsx +// your-button.jsx +import * as React from "react"; +import { Slot } from "radix-ui"; + +function Button({ asChild, children, leftElement, rightElement, ...props }) { + const Comp = asChild ? Slot.Root : "button"; + return ( + + {leftElement} + {children} + {rightElement} + + ); +} +``` + +### Usage + +```jsx +import { Button } from "./your-button"; + +export default () => ( + +); +``` + +### Event handlers + +Any prop that starts with `on` (e.g., `onClick`) is considered an event handler. + +When merging event handlers, `Slot` will create a new function where the child handler takes precedence over the slot handler. + +If one of the event handlers relies on `event.defaultPrevented` make sure that the order is correct. + +```jsx +import { Slot } from "radix-ui"; + +export default () => ( + { + if (!event.defaultPrevented) + console.log("Not logged because default is prevented."); + }} + > + +); +``` + +## API Reference + +### Root + +Anything you put inside this component will be hidden from the screen but will be announced by screen readers. + +## Accessibility + +This is useful in certain scenarios as an alternative to traditional labelling with `aria-label` or `aria-labelledby`. + +--- + + + +--- + +# Radix Themes - Complete Documentation + +> Radix Themes is a styled component library built on Radix Primitives with a beautiful default theme. + +# Overview + +## Getting started + +Install Radix Themes and start building in minutes + +# Getting started + +Install Radix Themes and start building in minutes. + +Radix Themes is a pre-styled component library that is designed to work out of the box with minimal configuration. If you are looking for the unstyled components, go to [Radix Primitives](/primitives). + +## Installation + +Getting up and running is quick and easy. + +### 1. Install Radix Themes + +Install the package from your command line. + +### 2. Import the CSS file + +Import the global CSS file at the root of your application. + +```ts +import "@radix-ui/themes/styles.css"; +``` + +### 3. Add the Theme component + +Add `Theme` to your application, wrapping the root component inside of `body`. + +```jsx line=7,9 +import { Theme } from "@radix-ui/themes"; + +export default function () { + return ( + + + + + + + + ); +} +``` + +### 4. Start building + +You are now ready to use Radix Themes components. + +```jsx +import { Flex, Text, Button } from "@radix-ui/themes"; + +export default function MyApp() { + return ( + + Hello from Radix Themes :) + + + ); +} +``` + +## Customizing your theme + +Configuration is managed and applied via the [Theme](/themes/docs/components/theme) component. + +### Basic configuration + +Pass [configuration](/themes/docs/components/theme) to the `Theme` to customize appearance. + +```jsx line=1 + + + +``` + +### Using the theme panel + +`ThemePanel` is a drop-in component that allows you to preview the theme in real time. Visit the [component playground](/themes/playground) to see it in action. + +To add `ThemePanel` to your app, import it from the package and drop it inside your root `Theme`. + +```jsx line=7 +import { Theme, ThemePanel } from "@radix-ui/themes"; + +export default function () { + return ( + + + + + ); +} +``` + +### Take it further + +Get the most out of Radix Themes by exploring more concepts and features. + +--- + +## Layout + +Get the layout concerns right. + +# Layout + +Get the layout concerns right. + +## Layout components + +Layout components are used to separate layout responsibilities from content and interactivity. This is _the_ separation of concerns that makes your app maintainable and easy to reason about, and understanding these principles is key to building your interfaces effectively. + +### Box + +[Box](/themes/docs/components/box) is the most fundamental layout component. Box is used to: + +- Provide spacing to child elements. +- Impose sizing constraints on content. +- Control layout behaviour within flex and grid containers. +- Hide content based on screen size using its responsive `display` prop. + +### Flex + +[Flex](/themes/docs/components/flex) component does everything that Box can do, but comes with an additional set of props to organize items along an axis. It provides convenient access to the CSS [flexbox properties](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) + +### Grid + +[Grid](/themes/docs/components/grid) is used to organize the content in columns and rows. Like Box and Flex, it’s made to provide convenient access to the underlying CSS [grid properties](https://css-tricks.com/snippets/css/complete-guide-grid/) without any magic of its own. + +### Section + +[Section](/themes/docs/components/section) provides a consistent vertical spacing between the larger parts of your page content, creating a sense of hierarchy and separation. There’s just a few pre-defined sizes for different spacing levels to keep things simple and consistent. + +### Container + +[Container](/themes/docs/components/container)’s sole responsibility is to provide a consistent `max-width` to the content it wraps. Like Section, it comes just with a couple of pre-defined sizes that work well with common breakpoints and typical content widths for comfortable reading. + +*** + +## Common layout props + +Each layout component has a set of it’s own specialized props and also a shared set of common layout props. All layout props support [responsive object values](/themes/docs/theme/breakpoints). + +### Padding + +Padding props can access the [space scale steps](/themes/docs/theme/spacing) or accept any valid [CSS padding value](https://developer.mozilla.org/en-US/docs/Web/CSS/padding). + +```jsx + + + +``` + +### Width + +Width props accept any valid [CSS width value](https://developer.mozilla.org/en-US/docs/Web/CSS/width). + +```jsx + + +``` + +### Height + +Height props accept any valid [CSS height value](https://developer.mozilla.org/en-US/docs/Web/CSS/height). + +```jsx + + +``` + +### Positioning + +Positioning props can change how the element is placed relative to the normal flow of the document. As usual, the corresponding CSS values are accepted for each property, and the [space scale steps](/themes/docs/theme/spacing) can be used for the offset values. + +```jsx + + + + + + + + +``` + +### Flex children + +Each layout component has props used to control the style when it is a child of a flex container. + +```jsx + + + +``` + +### Grid children + +Each layout component has props used to control the style when it is a child of a grid container. + +```jsx + + + + + + + + + +``` + +*** + +## Margin props + +Margin props are available on most components in order to provide spacing around the elements. They are not exclusive to layout components. + +Margin props can access the [space scale steps](/themes/docs/theme/spacing) or accept any valid [CSS margin value](https://developer.mozilla.org/en-US/docs/Web/CSS/margin) + +```jsx + + + + + + + + + + + + There are new commits. + + + + + + +``` + +#### 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" + + + + +``` + +*** + +## 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" + + + + Complete your account setup in settings + + + Complete your account setup in settings + + + Complete your account setup in settings + + + +``` + +#### 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 + + + +``` + +While `solid` is useful when you'd prefer to present information unobstructed. + +```jsx + + + +``` + +*** + +## 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. + +### 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. + +--- + +## Cursors + +Customizing cursors used for interactive elements. + +# Cursors + +Customizing cursors used for interactive elements. + +## 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" + + + + + + + + + Link + + + + + +``` + +## 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. + +--- + +## Dark mode + +Using appearance to manage and integrate dark mode. + +# Dark mode + +Using appearance to manage and integrate dark mode. + +## 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 + + + +``` + +## 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 ( + + + + + + ); +} +``` + +### 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"` + +--- + +## Theme overview + +Use the Theme component to change the look and feel of your UI. + +# Theme overview + +Use the Theme component to change the look and feel of your UI. + +## 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 + + + + + +``` + +## 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. + +--- + +## Radius + +Choosing the right radius setting in your theme. + +# Radius + +Choosing the right radius setting in your theme. + +## Theme setting + +Theme `radius` setting manages the radius factor applied to the components: + +```jsx line="1" + + + + + + + +``` + +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 + + + + + + + +``` + +## Radius overrides + +Certain components allow you to override the radius factor using their own `radius` prop. + +```jsx live=true + + + + + + + +``` + +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); +``` + +--- + +## Shadows + +Understanding the shadow styles used in your theme. + +# Shadows + +Understanding the shadow styles used in your theme. + +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); +``` + +--- + +## Spacing + +Overview of the space scale and scaling options. + +# Spacing + +Overview of the space scale and scaling options. + +## 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" + + + + + + + {person.name} + + + Approved invoice #3461 + + + + + +``` + +#### 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)); +} +``` + +--- + +## Typography + +Guidance for using and tuning typography. + +# Typography + +Guidance for using and tuning typography. + +## Base components + +Use [Text](/themes/docs/components/text) and [Heading](/themes/docs/components/heading) components to render titles and body copy. These components share `size` and `weight` props and map to the underlying type system to ensure consistent typography throughout your app. + +```jsx live=true +Typographic principles +The goal of typography is to relate font size, line height, and line width in a proportional way that maximizes beauty and makes reading easier and more pleasant. +``` + +## Formatting components + +Compose formatting components to add [emphasis](/themes/docs/components/em), [signal importance](/themes/docs/components/strong), present [code](/themes/docs/components/code) and more. + +```jsx live=true + + The most important thing to remember is,{" "} + stay positive. + +``` + +## Type scale + +The typographic system is based on a 9-step `size` scale. Every step has a corresponding font size, line height and letter spacing value which are all designed to be used in combination. + +```jsx live="true" +The quick brown fox jumps over the lazy dog. +``` + +## Font weight + +The following weights are supported. Weights can be [customized](/themes/docs/theme/typography#custom-font-weights) to map to your own typeface. + +```jsx live="true" + + + Light + Regular + Medium + Bold + + +``` + +## Font family + +By default, Radix Themes uses a system font stack for portability and legibility. Continue to the next section to learn about customizing your theme with a custom font. + +## Customization + +Radix Themes typography 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/typography.css) for the full list of the typographic tokens. + +Make sure that your CSS is applied after the Radix Themes styles so that it takes precedence. + +### Custom fonts + +You can provide your own fonts, however, how you choose to import and serve them is up to you. It is only required that you specify your named fonts using the correct syntax. + +To customize the font family used in your theme, remap the corresponding `font-family` tokens: + +```css +.radix-themes { + --default-font-family: /* Your custom default font */ --heading-font-family: + /* Your custom font for components */ --code-font-family: + /* Your custom font for components */ --strong-font-family: + /* Your custom font for components */ --em-font-family: + /* Your custom font for components */ --quote-font-family: + /* Your custom font for components */; +} +``` + +### With next/font + +To load custom fonts via [next/font](https://nextjs.org/docs/app/api-reference/components/font), use the [`variable`](https://nextjs.org/docs/app/api-reference/components/font#variable) option to define a CSS variable name. Then, add that CSS variable class to your HTML document. + +```jsx +import { Inter } from "next/font/google"; + +const inter = Inter({ + subsets: ["latin"], + display: "swap", + variable: "--font-inter", +}); + +export default function RootLayout({ children }) { + return ( + + {children} + + ); +} +``` + +Finally, assign the CSS variable in your custom CSS: + +```css +.radix-themes { + --default-font-family: var(--font-inter); +} +``` + +Be aware that you may encounter css import order issues if you are running the app router. See [common styling issues](/themes/docs/overview/styling#nextjs-import-order) for more information. + +### Custom font weights + +To customize the exact font weights used in your theme, remap the corresponding `font-weight` tokens to your own values: + +```css +.radix-themes { + --font-weight-light: 200; + --font-weight-regular: 300; + --font-weight-medium: 600; + --font-weight-bold: 800; +} +``` + +### Advanced settings + +There’s a number of advanced typographic features that can be customized. These include a font size multiplier for certain components, font style, letter spacing, and leading trim. For example, you can customize the headings to render with a relatively larger font size than your default font, different leading trim values, and tighter letter spacing: + +```css +.radix-themes { + --heading-font-family: "Untitled Sans", sans-serif; + --heading-font-size-adjust: 1.05; + --heading-font-style: normal; + --heading-leading-trim-start: 0.42em; + --heading-leading-trim-end: 0.38em; + --heading-letter-spacing: -0.01em; +} +``` + +--- + +# Components + +## Accessible Icon + +Makes icons accessible by adding a label. + +## API Reference + +This component inherits all props and functionality from the [Accessible Icon primitive](/primitives/docs/utilities/accessible-icon) utility. + +--- + +## Alert Dialog + +Modal confirmation dialog that interrupts the user and expects a response. + +```jsx live=true + + + + + + Revoke access + + Are you sure? This application will no longer be accessible and any + existing sessions will be expired. + + + + + + + + + + + + +``` + +## API Reference + +This component inherits parts and props from the [Alert Dialog primitive](/primitives/docs/components/alert-dialog) and is visually identical to [Dialog](/themes/docs/components/dialog), though with differing semantics and behavior. + +### Root + +Contains all the parts of the dialog. + +### Trigger + +Wraps the control that will open the dialog. + +### Content + +Contains the content of the dialog. This component is based on the `div` element. + +### Title + +An accessible title that is announced when the dialog is opened. This part is based on the [Heading](/themes/docs/components/heading) component with a pre-defined font size and leading trim on top. + +### Description + +An optional accessible description that is announced when the dialog is opened. This part is based on the [Text](/themes/docs/components/text) component with a pre-defined font size. + +If you want to remove the description entirely, remove this part and pass `aria-describedby={undefined}` to `Content`. + +### Action + +Wraps the control that will close the dialog. This should be distinguished visually from the `Cancel` control. + +### Cancel + +Wraps the control that will close the dialog. This should be distinguished visually from the `Action` control. + +## Examples + +### Size + +Use the `size` prop to control size of the dialog. It will affect the `padding` and `border-radius` of the Content. +Use it in conjunction with the `width`, `minWidth` and `maxWidth` props to control the width of the dialog. + +```jsx live=true line=6,17,28,39 + + + + + + + + The quick brown fox jumps over the lazy dog. + + + + + + + + + + + The quick brown fox jumps over the lazy dog. + + + + + + + + + + + The quick brown fox jumps over the lazy dog. + + + + + + + + + + + The quick brown fox jumps over the lazy dog. + + + + +``` + +### With inset content + +Use the [Inset](/themes/docs/components/inset) component to align content flush with the sides of the dialog. + +```jsx live=true + + + + + + Delete Users + + Are you sure you want to delete these users? This action is permanent and + cannot be undone. + + + + + + + Full name + Email + Group + + + + + + Danilo Sousa + danilo@example.com + Developer + + + + Zahra Ambessa + zahra@example.com + Admin + + + + + + + + + + + + + + + +``` + +--- + +## Aspect Ratio + +Displays content within a desired ratio. + +```jsx live=true + + A house in a forest + +``` + +## API Reference + +This component inherits props from the [Aspect Ratio primitive](/primitives/docs/components/aspect-ratio). + +--- + +## Avatar + +Profile picture, user initials or fallback icon. + +```jsx live=true + + + + +``` + +## API Reference + +This component inherits props from the [Avatar primitive](/primitives/docs/components/avatar). + +## Examples + +### Size + +Use the `size` prop to control the size of the avatar. + +```jsx live=true + + + + + + + + + + +``` + +### Variant + +Use the `variant` prop to control the visual style of the avatar. + +```jsx live=true + + + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + + + + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true + + + + + + + + + + + + +``` + +### Radius + +Use the `radius` prop to assign a specific radius value. + +```jsx live=true + + + + + +``` + +### Fallback + +Use the `fallback` prop to modify the rendered fallback element. + +```jsx live=true + + + + + + + + + } + /> + +``` + +--- + +## Badge + +Stylized badge element. + +```jsx live=true + + In progress + In review + Complete + +``` + +## API Reference + +This component is based on the `span` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Size + +Use the `size` prop to control the size. + +```jsx live=true + + + New + + + New + + + New + + +``` + +### Variant + +Use the `variant` prop to control the visual style. + +```jsx live=true scroll=true + + + New + + + New + + + New + + + New + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + New + New + New + New + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true + + + + New + + + New + + + New + + + New + + + + + New + + + New + + + New + + + New + + + +``` + +### Radius + +Use the `radius` prop to assign a specific radius value. + +```jsx live=true scroll=true + + + New + + + New + + + New + + +``` + +--- + +## Blockquote + +Block-level quotation from another source. + +```jsx live=true +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+``` + +## API Reference + +This component is based on the `blockquote` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Size + +Use the `size` prop to control the size. + +```jsx live=true scroll=true + + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ + +``` + +### Weight + +Use the `weight` prop to set the text weight. + +```jsx live=true + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true scroll=true + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live="true" + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ +``` + +### Truncate + +Use the `truncate` prop to truncate text with an ellipsis when it overflows its container. + +```jsx live=true line=2 + +
+ Perfect typography is certainly the most elusive of all arts. Sculpture in + stone alone comes near it in obstinacy. +
+ +``` + +--- + +## Box + +Fundamental layout building block. + +```jsx live=true + + + +``` + +## API Reference + +This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +Only the `display` prop values are unique to the Box component. + +The following props are shared between [Box](./box), [Flex](./flex), [Grid](./grid), [Container](./container) and [Section](./section) components. Read more about layout components in [Layout](/themes/docs/overview/layout). + +--- + +## Button + +Trigger an action or event, such as submitting a form or displaying a dialog. + +```jsx live=true + +``` + +## API Reference + +This component is based on the `button` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Size + +Use the `size` prop to control the size of the button. + +```jsx live=true + + + + + +``` + +### Variant + +Use the `variant` prop to control the visual style of the button. + +```jsx live=true scroll=true + + + + + + + +``` + +#### Ghost + +Use the `ghost` variant to display a button without chrome. Ghost buttons behave like text in layout, as they use a negative margin to optically align themselves against their siblings while maintaining the padding in active and hover states. + +```jsx live=true + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true scroll=true + + + + + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true scroll=true + + + + + + + + + + + + + + + + +``` + +### Radius + +Use the `radius` prop to assign a specific radius value. + +```jsx live=true scroll=true + + + + + +``` + +### With icons + +You can nest icons directly inside the button. An appropriate gap is provided automatically. + +```jsx live=true scroll=true + + + + + + + +``` + +### Loading + +Use the `loading` prop to display a loading spinner in place of button content, preserving the original size of the button in its normal state. The button will be disabled while loading. + +```jsx live=true scroll=true + + + + + + + +``` + +If you have an icon inside the button, you can use the button’s `disabled` state and wrap the icon in a standalone [Spinner](/themes/docs/components/spinner) to achieve a more sophisticated design. + +```jsx live=true scroll=true + + + + + + + +``` + +--- + +## Callout + +Short message to attract user’s attention. + +```jsx live=true + + + + + + You will need admin privileges to install and access this application. + + +``` + +## API Reference + +### Root + +Groups Icon and Text parts. This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +### Icon + +Provides width and height for the icon associated with the callout. This component is based on the `div` element. + +### Text + +Renders the callout text. This component is based on the `p` element. + +## Examples + +### Size + +Use the `size` prop to control the size. + +```jsx live=true + + + + + + + You will need admin privileges to install and access this application. + + + + + + + + + You will need admin privileges to install and access this application. + + + + + + + + + You will need admin privileges to install and access this application. + + + +``` + +### Variant + +Use the `variant` prop to control the visual style. + +```jsx live=true + + + + + + + You will need admin privileges to install and access + this application. + + + + + + + + + You will need admin privileges to install and access + this application. + + + + + + + + + You will need admin privileges to install and access + this application. + + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + + + + + + You will need admin privileges to install and access + this application. + + + + + + + + + You will need admin privileges to install and access + this application. + + + + + + + + + You will need admin privileges to install and access + this application. + + + +``` + +### High-contrast + +Use the `HighContrast` prop to add additional contrast. + +```jsx live=true line="11" + + + + + + + An update to Radix Themes is available. See what’s new in version 3.2.0. + + + + + + + + + An update to Radix Themes is available. See what’s new in version 3.2.0. + + + +``` + +### As alert + +Add a native [WAI-ARIA `alert` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) to the callout when the user’s immediate attention is required, like when an error message appears. The screen reader will be interrupted, announcing the new content immediately. + +```jsx live=true + + + + + + Access denied. Please contact the network administrator to view this page. + + +``` + +--- + +## Card + +Container that groups related content and actions. + +```jsx live=true + + + + + + + Teodros Girmay + + + Engineering + + + + + +``` + +## API Reference + +This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### As another element + +Use the `asChild` prop to render the card as a link or a button. This prop adds styles for the interactive states, like hover and focus. + +```jsx live=true + + + + + Quick start + + + Start building your next project in minutes + + + + +``` + +### Size + +Use the `size` prop to control the size. + +```jsx live=true + + + + + + + + Teodros Girmay + + + Engineering + + + + + + + + + + + + + Teodros Girmay + + + Engineering + + + + + + + + + + + + + Teodros Girmay + + + Engineering + + + + + + +``` + +### Variant + +Use the `variant` prop to control the visual style. + +```jsx live=true + + + + Quick start + + + Start building your next project in minutes + + + + + + Quick start + + + Start building your next project in minutes + + + +``` + +### With inset content + +Use the [Inset](/themes/docs/components/inset) component to align content flush with the sides of the card. + +```jsx live=true + + + + Bold typography + + + Typography is the art and technique of arranging type to + make written language legible, readable and appealing when displayed. + + + +``` + +--- + +## Checkbox Cards + +Set of interactive cards where multiple options can be selected at a time. + +```jsx live=true + + + + + A1 Keyboard + US Layout + + + + + Pro Mouse + Zero-lag wireless + + + + + Lightning Mat + Wireless charging + + + + +``` + +## API Reference + +This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +### Root + +### Item + +An item in the group that can be checked. + +## Examples + +### Size + +Use the `size` prop to control the size. + +```jsx live=true + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + +``` + +### Variant + +Use the `variant` prop to control the visual style. + +```jsx live=true + + + Agree to Terms + + + + Agree to Terms + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + + + Agree to Terms + + +``` + +### Disabled + +```jsx live=true + + + Off + On + + + + + Off + + + On + + + +``` + +--- + +## Checkbox Group + +Set of interactive buttons where multiple options can be selected at a time. + +```jsx live=true + + Fun + Serious + Smart + +``` + +## API Reference + +This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +### Root + +Contains all the parts of a checkbox group. + +### Item + +An item in the group that can be checked. + +## Examples + +### Size + +Use the `size` prop to control the checkbox size. + +```jsx live=true + + + + + + + + + + + + + +``` + +### Variant + +Use the `variant` prop to control the visual style of the checkboxes. + +```jsx live=true + + + + + + + + + + + + + + + + + + + + + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + + + + + + + + + + + + + + + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Alignment + +Composing `CheckboxGroup.Item` within `Text` automatically centers it with the first line of text. + +```jsx live="true" + + + + + Default + + + + + + Compact + + + + + + + + Default + + + + + + Compact + + + + + + + + Default + + + + + + Compact + + + + +``` + +It is automatically well-aligned with multi-line text too. + +### Disabled + +Use the native `disabled` attribute to create a disabled checkbox. + +```jsx live="true" + + + Off + On + + + + + Off + + + On + + + +``` + +--- + +## Checkbox + +Base input element to toggle an option on and off. + +```jsx live=true + + + + Agree to Terms and Conditions + + +``` + +## API Reference + +This component inherits props from the [Checkbox primitive](/primitives/docs/components/checkbox) and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Size + +Use the `size` prop to control the size of the checkbox. + +```jsx live=true + + + + + +``` + +### Variant + +Use the `variant` prop to control the visual style of the checkbox. + +```jsx live=true + + + + + + + + + + + + + + + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + + + + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true + + + + + + + + + + + + + +``` + +### Alignment + +Composing `Checkbox` within `Text` automatically centers it with the first line of text. + +```jsx live="true" + + + + Agree to Terms and Conditions + + + + + + Agree to Terms and Conditions + + + + + + Agree to Terms and Conditions + + + +``` + +It is automatically well-aligned with multi-line text too. + +```jsx live="true" + + + + I understand that these documents are + confidential and cannot be shared with a third party. + + + +``` + +### Disabled + +Use the native `disabled` attribute to create a disabled checkbox. + +```jsx live="true" + + + + + Not checked + + + + + + + Checked + + + + + + + Not checked + + + + + + + Checked + + + +``` + +### Indeterminate + +Use the `"indeterminate"` value to create an indeterminate checkbox. + +```jsx live="true" + + + + +``` + +--- + +## Code + +Marks text to signify a short fragment of computer code. + +```jsx live=true +console.log() +``` + +## API Reference + +This component is based on the `code` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Size + +Use the `size` prop to control text size. This prop also provides correct line height and corrective letter spacing—as text size increases, the relative line height and letter spacing decrease. + +```jsx live=true scroll=true + + console.log() + console.log() + console.log() + console.log() + console.log() + console.log() + console.log() + console.log() + console.log() + +``` + +### Variant + +Use the `variant` prop to control the visual style. + +```jsx live=true + + console.log() + console.log() + console.log() + console.log() + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + console.log() + console.log() + console.log() + console.log() + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true + + + + console.log() + + + console.log() + + + console.log() + + + console.log() + + + + + + console.log() + + + console.log() + + + console.log() + + + console.log() + + + +``` + +### Weight + +Use the `weight` prop to set the text weight. + +```jsx live="true" + + console.log() + console.log() + +``` + +### Truncate + +Use the `truncate` prop to truncate text with an ellipsis when it overflows its container. + +```jsx live=true line=2 + + linear-gradient(red, orange, yellow, green, blue); + +``` + +--- + +## Container + +Constrains the maximum width of page content. + +```jsx live=true + + + + + + + +``` + +## API Reference + +This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +Container sizes use the following `max-width` values, which may be customized if needed. + +The following props are shared between [Box](./box), [Flex](./flex), [Grid](./grid), [Container](./container) and [Section](./section) components. Read more about layout components in [Layout](/themes/docs/overview/layout). + +--- + +## Context Menu + +Menu representing a set of actions, displayed at the point of right click or long press. + +```jsx live=true + + + + + + Edit + Duplicate + + Archive + + + More + + Move to project… + Move to folder… + + Advanced options… + + + + + Share + Add to favorites + + + Delete + + + +``` + +## API Reference + +This component inherits props from the [Context Menu primitive](/primitives/docs/components/context-menu). + +### Root + +Contains all the parts of a context menu. + +### Trigger + +Wraps the element that will open the context menu. + +### Content + +The component that pops out when the context menu is open. + +### Label + +Used to render a label. It won't be focusable using arrow keys. + +### Item + +The component that contains the context menu items. + +### Group + +Used to group multiple `Item` parts. + +### RadioGroup + +Used to group multiple `RadioItem` parts. + +### RadioItem + +An item that can be controlled and rendered like a radio. + +### CheckboxItem + +An item that can be controlled and rendered like a checkbox. + +### Sub + +Contains all the parts of a submenu. + +### SubTrigger + +An item that opens a submenu. Must be rendered inside `ContextMenu.Sub`. + +### SubContent + +The component that pops out when a submenu is open. Must be rendered inside `ContextMenu.Sub`. + +## Examples + +### Size + +Use the `size` prop to control the size. + +```jsx live=true + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + +``` + +### Variant + +Use the `variant` prop to customize the visual style of the context menu. + +```jsx live=true + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). You can also pass `color` to a specific item to override for semantic reasons (i.e. a destructive action). + +```jsx live=true + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true line="18" + + + + + + + Edit + Duplicate + + Archive + + + + + + + + + Edit + Duplicate + + Archive + + + +``` + +--- + +## Data List + +Displays metadata as a list of key-value pairs. + +```jsx live=true + + + Status + + + Authorized + + + + + ID + + + u_2J89JSA4GJ + + + + + + + + Name + Vlad Moroz + + + Email + + vlad@workos.com + + + + Company + + + WorkOS + + + + +``` + +## API Reference + +This component is based on the `dl` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +### Root + +Contains all the parts of the data list. + +### Item + +Wraps a key-value pair. + +### Label + +Contains the key of the key-value pair. + +### Value + +Contains the value of the key-value pair. + +## Examples + +### Orientation + +Use the `orientation` prop to change the way the data list is layed-out. + +```jsx live=true + + + Name + Vlad Moroz + + + Email + + vlad@workos.com + + + + Company + + + WorkOS + + + + +``` + +### Size + +Use the `size` prop to change the size of the data list. + +```jsx live=true + + + + Name + Vlad Moroz + + + Email + + vlad@workos.com + + + + Company + + + WorkOS + + + + + + + + Name + Vlad Moroz + + + Email + + vlad@workos.com + + + + Company + + + WorkOS + + + + + + + + Name + Vlad Moroz + + + Email + + vlad@workos.com + + + + Company + + + WorkOS + + + + + +``` + +### Color + +Use the `color` prop on the Label part to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + + Name + Indigo + + + Name + Cyan + + + Name + Orange + + + Name + Crimson + + +``` + +### High-contrast + +Use the `highContrast` prop increase color contrast with the background. + +```jsx live=true + + + + Name + Indigo + + + Name + Cyan + + + Name + Orange + + + Name + Crimson + + + + + + + Name + + Indigo + + + + Name + + Cyan + + + + Name + + Orange + + + + Name + + Crimson + + + +``` + +--- + +## Dialog + +Modal dialog window displayed above the page. + +```jsx live=true + + + + + + + Edit profile + + Make changes to your profile. + + + + + + + + + + + + + + + + + +``` + +## API Reference + +This component inherits props from the [Dialog primitive](/primitives/docs/components/dialog). + +### Root + +Contains all the parts of a dialog. + +### Trigger + +Wraps the control that will open the dialog. + +### Content + +Contains the content of the dialog. This component is based on the `div` element. + +### Title + +An accessible title that is announced when the dialog is opened. This part is based on the [Heading](/themes/docs/components/heading) component with a pre-defined font size and leading trim on top. + +### Description + +An optional accessible description that is announced when the dialog is opened. This part is based on the [Text](/themes/docs/components/text) component with a pre-defined font size. + +If you want to remove the description entirely, remove this part and pass `aria-describedby={undefined}` to `Content`. + +### Close + +Wraps the control that will close the dialog. + +## Examples + +### Size + +Use the `size` prop to control size of the dialog. It will affect the `padding` and `border-radius` of the Content. +Use it in conjunction with the `width`, `minWidth` and `maxWidth` props to control the width of the dialog. + +```jsx live=true line=6,17,28,39 + + + + + + + + The quick brown fox jumps over the lazy dog. + + + + + + + + + + + The quick brown fox jumps over the lazy dog. + + + + + + + + + + + The quick brown fox jumps over the lazy dog. + + + + + + + + + + + The quick brown fox jumps over the lazy dog. + + + + +``` + +### With inset content + +Use the [Inset](/themes/docs/components/inset) component to align content flush with the sides of the dialog. + +```jsx live=true + + + + + + Users + + The following users have access to this project. + + + + + + + Full name + Email + Group + + + + + + Danilo Sousa + danilo@example.com + Developer + + + + Zahra Ambessa + zahra@example.com + Admin + + + + + + + + + + + + +``` + +--- + +## Dropdown Menu + +Menu representing a set of actions, triggered by a button. + +```jsx live=true + + + + + + Edit + Duplicate + + Archive + + + More + + Move to project… + Move to folder… + + + Advanced options… + + + + + Share + Add to favorites + + + Delete + + + +``` + +## API Reference + +This component inherits props from the [Dropdown Menu primitive](/primitives/docs/components/dropdown-menu). + +### Root + +Contains all the parts of a dropdown menu. + +### Trigger + +Wraps the control that will open the dropdown menu. + +### Trigger Icon + +An optional icon part. + +### Content + +The component that pops out when the dropdown menu is open. + +### Label + +Used to render a label. It won't be focusable using arrow keys. + +### Item + +The component that contains the dropdown menu items. + +### Group + +Used to group multiple `Item` parts. + +### RadioGroup + +Used to group multiple `RadioItem` parts. + +### RadioItem + +An item that can be controlled and rendered like a radio. + +### CheckboxItem + +An item that can be controlled and rendered like a checkbox. + +### Sub + +Contains all the parts of a submenu. + +### SubTrigger + +An item that opens a submenu. Must be rendered inside `DropdownMenu.Sub`. + +### SubContent + +The component that pops out when a submenu is open. Must be rendered inside `DropdownMenu.Sub`. + +## Examples + +### Size + +Use the `size` prop to control the size. + +```jsx live=true + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + +``` + +### Variant + +Use the `variant` prop to customize the visual style of the dropdown menu. + +```jsx live=true + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + + + + + + + Edit + Duplicate + + Archive + + + + Delete + + + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). You can also pass `color` to a specific item to override for semantic reasons (ie. destruction action). + +```jsx live=true + + + + + + + Edit + Duplicate + + Archive + + + + + + + + + Edit + Duplicate + + Archive + + + + + + + + + Edit + Duplicate + + Archive + + + + + + + + + Edit + Duplicate + + Archive + + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true line="24,54" + + + + + + + Edit + Duplicate + + Archive + + + + + + + + + Edit + Duplicate + + Archive + + + + + + + + + Edit + Duplicate + + Archive + + + + + + + + + Edit + Duplicate + + Archive + + + +``` + +--- + +## Em + +Marks text to stress emphasis. + +```jsx live=true + + We had to do something about it. + +``` + +## API Reference + +This component is based on the `em` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Truncate + +Use the `truncate` prop to truncate text with an ellipsis when it overflows its container. + +```jsx live=true line=2 + + + The goal of typography is to relate font size, line height, and line width + in a proportional way that maximizes beauty and makes reading easier and + more pleasant. + + +``` + +--- + +## Flex + +Component for creating flex layouts. + +```jsx live=true + + + + + + + + + + + + + + + + + +``` + +## API Reference + +This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +Use these props to create flex layouts. + +The following props are shared between [Box](./box), [Flex](./flex), [Grid](./grid), [Container](./container) and [Section](./section) components. Read more about layout components in [Layout](/themes/docs/overview/layout). + +--- + +## Grid + +Component for creating grid layouts. + +```jsx live=true + + + + + + + + +``` + +## API Reference + +This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +Use these props to create grid layouts. + +The following props are shared between [Box](./box), [Flex](./flex), [Grid](./grid), [Container](./container) and [Section](./section) components. Read more about layout components in [Layout](/themes/docs/overview/layout). + +## Examples + +### Responsive + +All props marked `Responsive`, such as `columns` and `rows` accept a [breakpoint object](/themes/docs/theme/breakpoints). For example, the following grid starts with 1 column, and uses 2 columns from the medium breakpoint. + +```jsx live=true + + + + + + + + +``` + +--- + +## Heading + +Semantic heading element. + +```jsx live=true +The quick brown fox jumps over the lazy dog +``` + +## API Reference + +This component is based on the `h1` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### As another element + +Use the `as` prop to change the heading level. This prop is purely semantic and does not change the visual appearance. + +```jsx live=true +Level 1 +Level 2 +Level 3 +``` + +### Size + +Use the `size` prop to control the size of the heading. The prop also provides correct line height and corrective letter spacing—as text size increases, the relative line height and letter spacing decrease. + +```jsx live=true scroll=true + + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + +``` + +### Weight + +Use the `weight` prop to set the text weight. + +```jsx live=true scroll=true + + The quick brown fox jumps over the lazy dog. + + + + The quick brown fox jumps over the lazy dog. + + + + The quick brown fox jumps over the lazy dog. + +``` + +### Align + +Use the `align` prop to set text alignment. + +```jsx live=true +Left-aligned +Center-aligned +Right-aligned +``` + +### Trim + +Use the `trim` prop to trim the leading space at the start, end, or both sides of the text box. + +The prop works similarly to the upcoming [half-leading control](https://www.w3.org/TR/css-inline-3/#leading-trim) spec, but uses a common [negative margin workaround](https://seek-oss.github.io/capsize/) under the hood for cross-browser support. + +```jsx live=true + + + Without trim + + + With trim + + +``` + +Trimming the leading is useful when dialing in vertical spacing in cards or other “boxy” components. Otherwise, padding looks larger on top and bottom than on the sides. + +```jsx live=true + + + + Without trim + + + The goal of typography is to relate font size, line height, and line width + in a proportional way that maximizes beauty and makes reading easier and + more pleasant. + + + + + + With trim + + + The goal of typography is to relate font size, line height, and line width + in a proportional way that maximizes beauty and makes reading easier and + more pleasant. + + + +``` + +The default trim values are configured for the system font stack that’s used by Radix Themes. If you are using custom fonts, you can [adjust](/themes/docs/theme/typography#customization) the trim values using the corresponding CSS variables. + +```css +.radix-themes { + --default-leading-trim-start: 0.42em; + --default-leading-trim-end: 0.36em; + --heading-leading-trim-start: 0.42em; + --heading-leading-trim-end: 0.36em; +} +``` + +### Truncate + +Use the `truncate` prop to truncate text with an ellipsis when it overflows its container. + +```jsx live=true line=2 + + The quick brown fox jumps over the lazy dog + +``` + +### Wrap + +Use the `wrap` prop to control text wrapping. + +```jsx live=true line=2 + + The quick brown fox jumps over the lazy dog + +``` + +```jsx live=true line=2 + + The quick brown fox jumps over the lazy dog + +``` + +```jsx live=true line=2 + + The quick brown fox jumps over the lazy dog + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). The text colors are designed to achieve at least Lc 60 APCA contrast over common background colors. + +```jsx live=true scroll=true + + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + The quick brown fox jumps over the lazy dog + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live="true" + + The quick brown fox jumps over the lazy dog. + + The quick brown fox jumps over the lazy dog. + + +``` + +--- + +## Hover Card + +For sighted users to preview content available behind a link. + +```jsx live=true + + Follow{" "} + + + + @radix_ui + + + + + + + + Radix + + + @radix_ui + + + React components, icons, and colors for building high-quality, + accessible UI. + + + + + {" "} + for updates. + +``` + +## API Reference + +This component inherits props from the [Hover Card primitive](/primitives/docs/components/hover-card). + +### Root + +Contains all the parts of the hover card. + +### Trigger + +Wraps the link that will open the hover card. + +### Content + +Contains the content of the open hover card. This component is based on the `div` element. + +## Examples + +### Size + +Use the `size` prop to control the size. + +```jsx live=true + + + + Size 1 + + + + Typography is the art and technique of arranging type + to make written language legible, readable and appealing when displayed. + + + + + + + Size 2 + + + + Typography is the art and technique of arranging type + to make written language legible, readable and appealing when displayed. + + + + + + + Size 3 + + + + Typography is the art and technique of arranging type + to make written language legible, readable and appealing when displayed. + + + + +``` + +### With inset content + +Use the [Inset](/themes/docs/components/inset) component to align content flush with the sides of the hover card. + +```jsx live=true + + Technology revolutionized{" "} + + + typography + + + + + + + Bold typography + + + + + Typography is the art and technique of arranging type + to make written language legible, readable and appealing when + displayed. The arrangement of type involves selecting typefaces, point + sizes, line lengths, line-spacing (leading), and letter-spacing + (tracking)… + + + + {" "} + in the latter twentieth century. + +``` + +--- + +## Icon Button + +Button designed specifically for usage with a single icon. + +```jsx live=true + + + +``` + +## API Reference + +This component is based on the `button` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Size + +Use the `size` prop to control the size of the button. + +```jsx live=true + + + + + + + + + + + + + +``` + +### Variant + +Use the `variant` prop to control the visual style of the button. + +```jsx live=true + + + + + + + + + + + + + + + + + +``` + +#### Ghost + +Use the `ghost` variant to display a button without chrome. Ghost buttons behave like text in layout, as they use a negative margin to optically align themselves against their siblings while maintaining the padding in active and hover states. + +```jsx live=true + + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true + + + + + + + + + + + + + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Radius + +Use the `radius` prop to assign a specific radius value. + +```jsx live=true + + + + + + + + + + + +``` + +### Loading + +Use the `loading` prop to display a loading spinner in place of button content. The button will be disabled while loading. + +```jsx live=true scroll=true + + + + + + + + + + + + + + + + + +``` + +--- + +## Inset + +Applies a negative margin to allow content to bleed into the surrounding container. + +```jsx live=true + + + + Bold typography + + + Typography is the art and technique of arranging type to + make written language legible, readable and appealing when displayed. + + + +``` + +## API Reference + +This component is based on the `div` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +--- + +## Kbd + +Represents keyboard input or a hotkey. + +```jsx live=true +Shift + Tab +``` + +## API Reference + +This component is based on the `kbd` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Size + +Use the `size` prop to control text size. + +```jsx live=true scroll=true + + Shift + Tab + Shift + Tab + Shift + Tab + Shift + Tab + Shift + Tab + Shift + Tab + Shift + Tab + Shift + Tab + Shift + Tab + +``` + +--- + +## Link + +Semantic element for navigation between pages. + +```jsx live=true +Sign up +``` + +## API Reference + +This component is based on the `a` element and supports [common margin props](/themes/docs/overview/layout#margin-props). + +## Examples + +### Size + +Use the `size` prop to control the size of the link. The prop also provides correct line height and corrective letter spacing—as text size increases, the relative line height and letter spacing decrease. + +```jsx live=true scroll=true + + + Sign up + + + Sign up + + + Sign up + + + Sign up + + + Sign up + + + Sign up + + + Sign up + + + Sign up + + + Sign up + + +``` + +### Weight + +Use the `weight` prop to set the text weight. + +```jsx live="true" + + + Sign up + + + Sign up + + + Sign up + + +``` + +### Truncate + +Use the `truncate` prop to truncate text with an ellipsis when it overflows its container. + +```jsx live=true line=2 + + + Sign up to the newsletter + + +``` + +### Color + +Use the `color` prop to assign a specific [color](/themes/docs/theme/color). + +```jsx live=true scroll=true + + + Sign up + + + Sign up + + + Sign up + + + Sign up + + +``` + +### High-contrast + +Use the `highContrast` prop to increase color contrast with the background. + +```jsx live=true scroll=true + + + Sign up + + + Sign up + + +``` + +### Underline + +Use the `underline` prop to manage the visibility of the underline affordance. + +```jsx live="true" scroll=true + + + Sign up + + + Sign up + + +``` + +--- + +## Popover + +Floating element for displaying rich content, triggered by a button. + +```jsx live=true + + + + + + + + +