base-ui Documentation

Unstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.

11,140 stars TypeScript TypeScript 1 file · ~151,789 tokens #accessibility#base-ui#components#design-system#react#react-components#ui#wai-aria
RAW Doc

Technical Documentation: mui/base-ui

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

Base UI

From the creators of Radix, Floating UI, and Material UI, Base UI is an unstyled UI component library for building accessible user interfaces.

Documentation

To get started, check out the Base UI documentation.

Contributing

Read our contributing guide to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.

Releases

To see the latest updates, check out the releases.

Community

  • Discord For community support, questions, and tips, join our Discord.
  • X To stay up-to-date on new releases and announcements follow Base UI on X.
  • Bluesky We're also on Bluesky.

Team

License

This project is licensed under the terms of the MIT license.

Overview (`docs/README.md`)

Docs

This is the documentation of Base UI.

To start the docs site in development mode, from the project root, run:

bash
pnpm start

If you do not have pnpm installed, select your OS and follow the instructions on the pnpm website.

Package managers other than pnpm (like npm or Yarn) are not supported and don't work.

How can I add a new demo to the documentation?

You can follow this guide
on how to get started contributing to Base UI.

Error code extraction

Errors in production are minified. They are extracted out of the source code by running the command

bash
pnpm extract-error-codes

This updates the ./src/error-codes.json file with the newly extracted errors.

Important: If you just altered the text of an error, you are allowed to update the existing error code with the new text in ./src/error-codes.json, but only under the following conditions:

  1. There hasn't been an update to the semantic meaning of the error message. Error codes need to outlive Base UI versions, so the same code must mean the same thing across versions.
  2. There hasn't been a change in parameters, no added and no removed.

In both of those cases, always create a new error code lline in ./src/error-codes.json.

Overview (`scripts/README.md`)

Scripts

Release

[!NOTE]
These instructions are intended for the Base UI core team, who have the permissions required to publish releases.

A typical release goes like this:

Prepare the release of the packages

  1. Create a Git branch off the current main branch.
  2. Update the root /package.json's version. It should match the target version of @base-ui/react.
  3. Generate the changelog with pnpm release:changelog
    The output must be prepended to the top level CHANGELOG.md.
    Run pnpm release:changelog --help for more information.
  4. Update the changelog as necessary. In particular, describe all the breaking changes.
  5. Generate the changelog in a format suitable for the docs with pnpm release:changelog:docs.
  6. Create a new release page at docs/src/app/(docs)/react/overview/releases/<version-slug>/page.mdx (where <version-slug> uses hyphens, for example, v1-1-0 for v1.1.0). Paste the generated changelog there, following the format of existing release pages (title, <Subtitle> with the date, <Meta> tag, remove contributors).
  7. Copy the changes made in point 4 to the new release page and adapt to the required format.
  8. Add a new entry to docs/src/data/releases.ts with the version, versionSlug, date, and highlights. Move the latest: true flag to the new release if appropriate.
  9. Run pnpm release:version. Keep the package versions of stable public packages (@base-ui/react) the same as the root package.json version.
  10. Open a PR with changes and wait for review and green CI.
  11. When the PR is close to being merged, announce a merge freeze on the Base UI Slack channel so no other changes land on the main branch until the release is published and the docs are deployed.
  12. Merge the PR once the CI is green and it has been approved.

Release the packages

  1. Run pnpm release:publish. You may be asked to authenticate with GitHub when running the command for the first time or after a very long time.

  2. It'll automatically fetch the latest merged release PR and ask for confirmation before publishing.

  3. If you already know the sha of the commit, you can pass it directly like pnpm release:publish --sha <your-sha>.

  4. Other flags for the command:

    • --dry-run Used for debugging. Or directly run pnpm release:publish:dry-run.
    • --dist-tag Use to publish legacy or canary versions.

  5. This command invokes the Publish GitHub action. It'll log the URL which can be opened to see the latest workflow run.

  6. The next screen shows "@username requested your review to deploy to npm-publish", click "Review deployments" and authorize your workflow run. Never approve workflow runs you didn't initiate.

Publish the documentation

The documentation must be updated on the docs-vX branch (docs-v1 for v1.X releases, docs-v2 for v2.X releases, etc.)

Force-push the latest upstream master to the documentation release branch to deploy the documentation with the latest changes:

bash
pnpm docs:deploy

You can follow the deployment process on the Netlify Dashboard
Once deployed, it will be accessible at https://base-ui.netlify.app/ for the docs-v1 deployment.

Once the docs are deployed, lift the merge freeze on the Base UI Slack channel.

GitHub release

After the documentation deployment is done, review, and then publish the release that was created in draft mode during the release step GitHub releases page
Make sure to check the Set as a pre-release checkbox if publishing an unstable version.

Overview (`test/README.md`)

Testing

Thanks for writing tests! Here's a quick run-down on our current setup.

Getting started

  1. Add a unit test to packages/*/src/TheUnitInQuestion/TheUnitInQuestion.test.js or an integration test packages/*/test/.
  2. Run pnpm test:jsdom TheUnitInQuestion.
  3. Implement the tested behavior
  4. Open a PR once the test passes or if you want somebody to review your work

Tools we use

Writing tests

For all unit tests, please use the return value of createRenderer from #test-utils.
It prepares the test suite and returns a function with the same interface as
render from @testing-library/react.

js
describe('test suite', () => {
  const { render } = createRenderer();

  test('first', async () => {
    await render(<input />);
  });
});

For new tests please use Vitest's native expect() and vi.fn() APIs. Prefer expressive built-in matchers along with
@testing-library/jest-dom DOM assertions where applicable.

Deciding where to put a test is (like naming things) a hard problem:

  • When in doubt, put the new test case directly in the unit test file for that component, for example packages/react/src/accordion/root/AccordionRoot.test.tsx.
  • If your test requires multiple components from the library create a new integration test.
  • If you find yourself using a lot of data-testid attributes or you're accessing
    a lot of styles consider adding a component (that doesn't require any interaction)
    to test/regressions/tests/, for example test/regressions/tests/List/ListWithSomeStyleProp
  • If you have to dispatch and compose many different DOM events prefer end-to-end tests (Checkout the end-to-end testing readme for more information.)

Unexpected calls to `console.error` or `console.warn`

By default, our test suite fails if any test recorded console.error or console.warn calls that are unexpected.

The failure message includes the full test name (suite names + test name).
This should help locating the test in case the top of the stack can't be read due to excessive error messages.
The error includes the logged message as well as the stacktrace of that message.

You can explicitly expect no console calls for when you're adding a regression test.
This makes the test more readable and properly fails the test in watchmode if the test had unexpected console calls.

Writing a test for `console.error` or `console.warn`

If you add a new warning via console.error or console.warn you should add tests that expect this message.
For tests that expect a call you can use our custom toWarnDev or toErrorDev matchers.
The expected messages must be a subset of the actual messages and match the casing.
The order of these messages must match as well.

Example:

jsx
function SomeComponent({ variant }) {
  if (process.env.NODE_ENV !== 'production') {
    if (variant === 'unexpected') {
      console.error("That variant doesn't make sense.");
    }
    if (variant !== undefined) {
      console.error('`variant` is deprecated.');
    }
  }

  return <div />;
}
expect(() => {
  render(<SomeComponent variant="unexpected" />);
}).toErrorDev(["That variant doesn't make sense.", '`variant` is deprecated.']);
js
function SomeComponent({ variant }) {
  if (process.env.NODE_ENV !== 'production') {
    if (variant === 'unexpected') {
      console.error("That variant doesn't make sense.");
    }
    if (variant !== undefined) {
      console.error('`variant` is deprecated.');
    }
  }

  return <div />;
}
expect(() => {
  render(<SomeComponent />);
}).not.toErrorDev();

Commands

We uses a wide range of tests approach as each of them comes with a different
trade-off, mainly completeness vs. speed.

React API level

Debugging tests

If you want to debug tests with the, for example Chrome inspector (chrome://inspect) you can run pnpm test:jsdom <testFilePattern> --debug.
Note that the test will not get executed until you start code execution in the inspector.

Running a browser test (pnpm test:chromium) locally opens a browser window that lets you set breakpoints.

Run the core unit test suite

To run all of the unit tests run pnpm test:jsdom.
It runs a Vitest CLI that lets you filter tests and watches for changes.

If you want to run only tests from a particular file, append its name to the commandline: pnpm test:jsdom TheUnitInQuestion

DOM API level

Run the test suite in the browser

pnpm test:chromium
pnpm test:firefox

Testing the components with jsdom sometimes isn't enough, as it doesn't support all the APIs.
We need to make sure they will behave as expected with a real DOM.
To solve that problem we use Vitest in browser mode.

Our tests run on different browsers to increase the coverage:

In development mode, if pnpm test:chromium or pnpm test:firefox fails with this error "Cannot start ChromeHeadless. Can not find the binary", you can solve it by installing the missing headless browsers: pnpm playwright install --with-deps.

BrowserStack

We only use BrowserStack for non-PR commits to save resources.
BrowserStack rarely reports actual issues so we only use it as a stop-gap for releases not merges.

To force a run of BrowserStack on a PR you have to run the pipeline with browserstack-force set to true.
For example, you've opened a PR with the number 64209 and now after everything is green you want to make sure the change passes all browsers:

bash
curl --request POST \
  --url https://circleci.com/api/v2/project/gh/mui/base-ui/pipeline \
  --header 'content-type: application/json' \
  --header 'Circle-Token: $CIRCLE_TOKEN' \
  --data-raw '{"branch":"pull/64209/head","parameters":{"browserstack-force":true}}'

Browser API level

In the end, components are going to be used in a real browser.
The DOM is just one dimension of that environment,
so we also need to take into account the rendering engine.

Visual regression tests

Check out the visual regression testing readme for more information.

end-to-end tests

Checkout the end-to-end testing readme for more information.

Screen reader tests

Screen reader tests use Guidepup with the existing end-to-end
fixtures. They run in a headed Chromium browser with VoiceOver on macOS or NVDA on Windows.
The screen reader must use English because the tests and Guidepup's navigation match English
announcements.

The setup package is installed by pnpm install. On macOS, developers who run these tests must
configure their host once:

bash
pnpm test:screen-reader:setup

This macOS-level step is intentionally not run during pnpm install because it changes system
settings and may require manual permission prompts.

If the test fails with Failed to mount Guidepup preferences and an EPERM error, grant Full
Disk Access to the terminal, IDE, or other application running the test under System Settings
→ Privacy & Security → Full Disk Access. Fully quit and reopen that application before retrying.

Then run pnpm test:screen-reader. The compatible screen reader assets are installed
automatically before the test.

GitHub Actions runs the same cross-platform test with NVDA and Chrome on a Windows Server 2025
runner.

Development

When working on the visual regression tests you can run pnpm test:regressions:dev in the background to constantly rebuild the views used for visual regression testing.
To actually take the screenshots you can then run pnpm test:regressions:run.
You can view the screenshots in test/regressions/screenshots/chrome.

Alternatively, you might want to open http://localhost:5173 (while pnpm test:regressions:dev is running) to view individual views separately.

Testing multiple versions of React

You can check integration of different versions of React (for example different release channels or PRs to React) by running pnpm dlx @mui/internal-code-infra@canary set-version-overrides --pkg react@<version>.

Possible values for version:

  • default: stable (minimum supported React version)
  • a tag on npm, for example next, experimental or latest
  • an older version, for example ^17.0.0

CI

You can pass the same version to our CircleCI pipeline as well:

With the following API request we're triggering a run of the default workflow in
PR #24289 for react@next

bash
curl --request POST \
  --url https://circleci.com/api/v2/project/gh/mui/base-ui/pipeline \
  --header 'content-type: application/json' \
  --header 'Circle-Token: $CIRCLE_TOKEN' \
  --data-raw '{"branch":"pull/24289/head","parameters":{"react-version":"next"}}'

Overview (`examples/tanstack-start-tailwind-css/README.md`)

Base UI + TanStack Start

This is a simple TanStack Start app with Base UI components styled using Tailwind CSS.

Getting started

Note: TanStack Start Server Functions used in the combobox example may not work in StackBlitz due to lack of AsyncLocalStorage support.

Or to run it locally:

bash
pnpm install
pnpm start

This starts a Vite development server at http://localhost:3000. Node.js version 20.19+ or 22.12+ is required.

Building for production

To build a production bundle:

bash
pnpm build

To preview the production build:

bash
pnpm serve

TypeScript

To check the types:

bash
pnpm typescript

Linting & Formatting

This project uses ESLint and prettier for linting and formatting. ESLint is configured using @tanstack/eslint-config. The following scripts are available:

bash
# lint only
pnpm lint
# lint and prettier with autofix
pnpm check

Routing

This app uses TanStack Router with a file based router. Routes are managed as files in src/routes. The router also provides loader functionality to load data for a route before it's rendered.

Overview (`examples/vite-css/README.md`)

React + TypeScript + Vite

This template provides a minimal setup to get React + Base UI (styled with plain CSS) working in Vite with HMR and some ESLint rules.

Getting Started

Prerequisites

  • Node.js (version 20.19+ or 22.12+ is required)
  • pnpm (or use npm/yarn if preferred)

Install dependencies

bash
pnpm install

Run the development server

bash
pnpm dev

This will start the Vite development server. Open http://localhost:5173 to view the app in your browser.

Build for production

bash
pnpm build

Preview the production build

bash
pnpm preview

Make sure to build the project for production with pnpm build first.

Linting

To run ESLint:

bash
pnpm lint

Overview (`packages/react/README.md`)

Base UI is a library of unstyled React components. You gain complete control over your app's CSS and accessibility features.

Installation

Install the package in your project directory with:

bash
npm install @base-ui/react

Documentation

Visit base-ui.com to view the full documentation.

Questions

For how-to questions that don't involve making changes to the code base, please use Stack Overflow instead of GitHub issues.
Use the "base-ui" tag on Stack Overflow to make it easier for the community to find your question.

Contributing

Read the contributing guide to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.

Contributing to Base UI is about more than just issues and pull requests!
There are many other ways to support Base UI beyond contributing to the code base.

Changelog

The changelog is regularly updated to reflect what's changed in each new release.

Roadmap

Future plans and high-priority features and enhancements can be found in the roadmap.

License

This project is licensed under the terms of the MIT license.

Security

For details of supported versions and contact details for reporting security issues, please refer to the security policy.

Overview (`packages/utils/README.md`)

@base-ui/utils

A collection of React utility functions for Base UI.

Overview (`playground/vite-app/README.md`)

Base UI Vite playground

A small Vite + React app used for local experimentation and performance benchmarks against the Base UI source in this repo.

Usage

Dev mode

bash
pnpm dev

Production mode

bash
pnpm build
pnpm serve

Profiling build

This app supports a profiling build that aliases react-dom/client to react-dom/profiling.
This enables React Performance Tracks in Chrome Developer Tools profiler.

bash
pnpm build:profile
pnpm serve

React Performance Tracks

React can annotate the browser Performance panel with scheduling, commit, and component timing tracks in development and profiling builds. To use it:

  1. Install the React DevTools browser extension.
  2. Use the profiling build above (or pnpm -C playground/vite-app dev) and open the app in a Chromium-based browser.
  3. Open DevTools > Performance, start a recording, then interact with the app.
  4. Look for the React tracks in the timeline.

Reference: https://react.dev/reference/dev-tools/react-performance-tracks

Deployment

The playground is deployed alongside the main docs.
pnpm docs:build in the repo root builds the playground and copies the output to the Next.js export directory.
The playground is then available under /vite-playground.

Overview (`test/e2e/README.md`)

end-to-end testing

End-to-end tests (short e2e) are split into two parts:

  1. The rendered UI, or test fixtures
  2. Instrumentation of fixtures with a simple Vite app

Rendered UI

The composition of all tests happens in ./main.tsx.
The rendered UI is located inside a separate file in ./fixtures and written as a React component.
If you're adding a new test prefer a new component instead of editing existing files since that might unknowingly alter existing tests.

Instrumentation

We're using playwright to replay user actions.
Each test tests only a single fixture.
A fixture can be loaded with await renderFixture(fixturePath), for example renderFixture('FocusTrap/OpenFocusTrap').

Commands

For development pnpm test:e2e:dev and pnpm test:e2e:run --watch in separate terminals is recommended.

command description
pnpm test:e2e Full run
pnpm test:e2e:dev Prepares the fixtures and runs a Vite dev server
pnpm test:e2e:run Runs the tests (requires pnpm test:e2e:dev or pnpm test:e2e:build+pnpm test:e2e:server)
pnpm test:e2e:build Builds the Vite bundle for viewing fixtures
pnpm test:e2e:server Serves the fixture bundle.

Overview (`test/regressions/README.md`)

Visual regression testing

Visual regression tests are split into two parts:

  1. The rendered UI, or test fixtures
  2. Instrumentation of fixtures with a simple Vite app

Rendered UI

The composition of all tests happens in ./main.tsx.
The rendered UI is either:

  1. located inside a separate file in ./fixtures and written as a React component.

    Here is an example with the Menu component.

  2. a demo from docs/src/app/(docs)/react

    By default all demos are included.
    We exclude demos if they are redundant or flaky etc.
    The logic for this exclusion is handled (like the composition) in ./main.tsx

If you introduce new behavior, prefer adding a demo to the documentation to solve documentation and testing with one file.
If you're adding a new test prefer a new component instead of editing existing files since that might unknowingly alter existing tests.

Instrumentation

Manual

pnpm test:regressions:dev will build all fixtures and render an overview page that lists all fixtures.
This can be used to debug individual fixtures.
By default, a devtools-like view is shown that can be disabled by appending #no-dev to the URL, for example http://localhost:5173/docs-components-checkbox-group-demos-hero-tailwind/index.tsx#no-dev or forced by appending #dev to the URL, for example http://localhost:5173/docs-components-checkbox-group-demos-hero-tailwind/index.tsx#dev.

Automatic

We're using playwright to iterate over each fixture and take a screenshot.
It allows catching regressions like this one:

Screenshots are saved in ./screenshots/$BROWSER_NAME/.
Each test tests only a single fixture.
A fixture can be loaded with await renderFixture(fixturePath), for example renderFixture('FocusTrap/OpenFocusTrap').

Commands

For development run pnpm test:regressions:dev.

command description
pnpm test:regressions Full run
pnpm test:regressions:dev Prepares the fixtures and runs a Vite dev server
pnpm test:regressions:run Runs the tests (requires pnpm test:regressions:dev or pnpm test:regressions:build+pnpm test:regressions:server)
pnpm test:regressions:build Builds the Vite bundle for viewing fixtures
pnpm test:regressions:server Serves the fixture bundle.

Overview (`docs/src/css/README.md`)

Styling conventions

Read the index.css file for more information on the styling conventions.

Overview (`test/regressions/manual/README.md`)

manual visual regression tests

These are expensive tests that should only be consulted if you suspect that something changed.
Move the test you want to check inside a temporary folder in ../test and run the visual regression test suite to get a screenshot.

Package.Json (`docs/package.json`)

{
"name": "docs",
"private": true,
"scripts": {
"build": "rimraf ./export && cross-env NODE_ENV=production NODE_OPTIONS=--max_old_space_size=8192 next build --webpack && pnpm link-check",
"build:clean": "rimraf .next && pnpm build",
"dev": "next dev --port 3005",
"deploy": "git fetch upstream master && git push -f upstream FETCH_HEAD:docs-v1",
"serve": "serve ./export -l 3010",
"docs-infra": "docs-infra",
"validate": "pnpm internal-validate --command "pnpm validate"",
"internal-validate": "docs-infra validate",
"typescript": "tsc -b tsconfig.json",
"link-check": "tsx ./scripts/reportBrokenLinks.mts",
"generate-llms": "node --experimental-strip-types ./scripts/generateLlmTxt/index.mjs"
},
"dependencies": {
"@base-ui/react": "workspace:",
"@base-ui/utils": "workspace:",
"@mdx-js/loader": "^3.1.1",
"@mdx-js/react": "^3.1.1",
"@mui/internal-docs-infra": "0.13.1-canary.7",
"@next/mdx": "^16.3.6",
"@react-spring/web": "^10.1.2",
"@stefanprobst/rehype-extract-toc": "^3.0.0",
"@tanstack/react-form": "^1.33.5",
"@tanstack/react-virtual": "^3.14.13",
"@types/mdx": "^2.0.14",
"clipboard-copy": "^4.0.1",
"clsx": "^2.1.1",
"es-toolkit": "^1.52.0",
"estree-util-value-to-estree": "^3.5.0",
"globby": "^16.2.4",
"hast": "^1.0.0",
"hast-util-heading-rank": "^3.0.0",
"hast-util-to-string": "^3.0.1",
"lucide-react": "^1.48.0",
"lz-string": "^1.5.0",
"match-sorter": "^8.3.0",
"next": "16.3.6",
"postcss": "^8.5.28",
"postcss-custom-media": "^12.0.2",
"postcss-import": "^17.0.0",
"radix-ui": "^1.6.7",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"react-error-boundary": "6.1.6",
"react-hook-form": "^7.89.0",
"remark-gfm": "^4.0.1",
"remark-parse": "^11.0.0",
"remark-rehype": "^11.1.2",
"remark-typography": "0.8.9",
"scroll-into-view-if-needed": "3.1.0",
"server-only": "^0.0.1",
"unist-util-visit-parents": "^6.0.2"
},
"devDependencies": {
"@mdx-js/mdx": "3.1.1",
"@tailwindcss/postcss": "4.3.3",
"@types/gtag.js": "0.0.20",
"@types/hast": "3.0.5",
"@types/node": "22.20.4",
"@types/react": "19.3.0",
"@types/react-dom": "19.3.0",
"@types/unist": "3.0.3",
"cross-env": "10.1.0",
"mdast-util-mdx-jsx": "3.2.0",
"motion": "13.4.5",
"prettier": "3.9.9",
"remark-stringify": "11.0.0",
"rimraf": "6.1.3",
"serve": "14.2.6",
"tailwindcss": "4.3.3",
"typescript": "npm:@typescript/[email protected]",
"unified": "11.0.5",
"unist-util-visit": "5.1.0",
"zod": "4.6.5"
}
}

Tsconfig.Json (`docs/tsconfig.json`)

{
"extends": "../tsconfig.base.json",
"include": [
"data",
"scripts/.mts",
"src",
"types.d.ts",
"next-env.d.ts",
"next.config.mjs",
".next/types/**/.ts",
"export/types/**/.ts"
],
"compilerOptions": {
"allowJs": true,
"isolatedModules": true,
/ files are emitted by webpack /
"noEmit": true,
"noUnusedLocals": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"esModuleInterop": true,
"types": ["react"],
"incremental": true,
"composite": true,
"module": "esnext",
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"plugins": [
{
"name": "next"
}
],
"paths": {
"@base-ui/react": ["../packages/react/src"],
"@base-ui/react/": ["../packages/react/src/"],
"@base-ui/utils/": ["../packages/utils/src/*"]
},
"strictNullChecks": true,
"jsx": "preserve"
},
"exclude": ["node_modules"],
"references": [
{
"path": "../packages/react/tsconfig.typecheck.json"
}
]
}

Src Error Codes.Json (`docs/src/error-codes.json`)

{
"1": "Unsupported number of selectors",
"2": "Unsupported number of arguments",
"3": "Base UI: CheckboxGroupContext is missing. CheckboxGroup parts must be placed within .",
"4": "Base UI: DirectionContext is missing.",
"5": "Base UI: MenubarContext is missing. Menubar parts must be placed within .",
"7": "Base UI: ToggleGroupContext is missing. ToggleGroup parts must be placed within .",
"8": "Base UI: Render element or function are not defined.",
"9": "Base UI: AccordionItemContext is missing. Accordion parts must be placed within <Accordion.Item>.",
"10": "Base UI: AccordionRootContext is missing. Accordion parts must be placed within <Accordion.Root>.",
"11": "Base UI: <AlertDialog.Portal> is missing.",
"12": "Base UI: AlertDialogRootContext is missing. AlertDialog parts must be placed within <AlertDialog.Root>.",
"13": "Base UI: AvatarRootContext is missing. Avatar parts must be placed within <Avatar.Root>.",
"14": "Base UI: CheckboxRootContext is missing. Checkbox parts must be placed within <Checkbox.Root>.",
"15": "Base UI: CollapsibleRootContext is missing. Collapsible parts must be placed within <Collapsible.Root>.",
"16": "Base UI: CompositeRootContext is missing. Composite parts must be placed within <Composite.Root>.",
"17": "Base UI: ComboboxChipContext is missing. ComboboxChip parts must be placed within <Combobox.Chip>.",
"18": "Base UI: ComboboxGroupContext is missing. ComboboxGroup parts must be placed within <Combobox.Group>.",
"19": "Base UI: ComboboxItemContext is missing. ComboboxItem parts must be placed within <Combobox.Item>.",
"20": "Base UI: <Combobox.Portal> is missing.",
"21": "Base UI: <Combobox.Popup> and <Combobox.Arrow> must be used within the <Combobox.Positioner> component",
"22": "Base UI: ComboboxRootContext is missing. Combobox parts must be placed within <Combobox.Root>.",
"23": "Base UI: ComboboxFloatingContext is missing. Combobox parts must be placed within <Combobox.Root>.",
"24": "Base UI: ComboboxItemsContext is missing. Combobox parts must be placed within <Combobox.Root>.",
"25": "Base UI: ContextMenuRootContext is missing. ContextMenu parts must be placed within <ContextMenu.Root>.",
"26": "Base UI: <Dialog.Portal> is missing.",
"27": "Base UI: DialogRootContext is missing. Dialog parts must be placed within <Dialog.Root>.",
"28": "Base UI: FieldRootContext is missing. Field parts must be placed within <Field.Root>.",
"29": "[Floating UI]: Invalid grid - item width at index %s is greater than grid columns",
"30": "Base UI: MenuCheckboxItemContext is missing. MenuCheckboxItem parts must be placed within <Menu.CheckboxItem>.",
"31": "Base UI: MenuGroupContext is missing. Menu group parts must be used within <Menu.Group> or <Menu.RadioGroup>.",
"32": "Base UI: <Menu.Portal> is missing.",
"33": "Base UI: MenuPositionerContext is missing. MenuPositioner parts must be placed within <Menu.Positioner>.",
"34": "Base UI: MenuRadioGroupContext is missing. MenuRadioGroup parts must be placed within <Menu.RadioGroup>.",
"35": "Base UI: MenuRadioItemContext is missing. MenuRadioItem parts must be placed within <Menu.RadioItem>.",
"36": "Base UI: MenuRootContext is missing. Menu parts must be placed within <Menu.Root>.",
"37": "Base UI: <Menu.SubmenuTrigger> must be placed in <Menu.SubmenuRoot>.",
"38": "Base UI: MeterRootContext is missing. Meter parts must be placed within <Meter.Root>.",
"39": "Base UI: NavigationMenuItem parts must be used within a <NavigationMenu.Item>.",
"40": "Base UI: <NavigationMenu.Portal> is missing.",
"41": "Base UI: NavigationMenuRootContext is missing. Navigation Menu parts must be placed within <NavigationMenu.Root>.",
"42": "Base UI: NavigationMenuPositionerContext is missing. NavigationMenuPositioner parts must be placed within <NavigationMenu.Positioner>.",
"43": "Base UI: NumberFieldRootContext is missing. NumberField parts must be placed within <NumberField.Root>.",
"44": "Base UI: NumberFieldScrubAreaContext is missing. NumberFieldScrubArea parts must be placed within <NumberField.ScrubArea>.",
"45": "Base UI: is missing.",
"46": "Base UI: PopoverPositionerContext is missing. PopoverPositioner parts must be placed within .",
"47": "Base UI: PopoverRootContext is missing. Popover parts must be placed within .",
"48": "Base UI: is missing.",
"49": "Base UI: PreviewCardPositionerContext is missing. PreviewCardPositioner parts must be placed within .",
"50": "Base UI: PreviewCardRootContext is missing. PreviewCard parts must be placed within .",
"51": "Base UI: ProgressRootContext is missing. Progress parts must be placed within .",
"52": "Base UI: RadioRootContext is missing. Radio parts must be placed within <Radio.Root>.",
"53": "Base UI: ScrollAreaRootContext is missing. ScrollArea parts must be placed within <ScrollArea.Root>.",
"54": "Base UI: ScrollAreaScrollbarContext is missing. ScrollAreaScrollbar parts must be placed within <ScrollArea.Scrollbar>.",
"55": "Base UI: ScrollAreaViewportContext missing. ScrollAreaViewport parts must be placed within <ScrollArea.Viewport>.",
"56": "Base UI: SelectGroupContext is missing. SelectGroup parts must be placed within <Select.Group>.",
"57": "Base UI: SelectItemContext is missing. SelectItem parts must be placed within <Select.Item>.",
"58": "Base UI: <Select.Portal> is missing.",
"59": "Base UI: SelectPositionerContext is missing. SelectPositioner parts must be placed within <Select.Positioner>.",
"60": "Base UI: SelectRootContext is missing. Select parts must be placed within <Select.Root>.",
"61": "Base UI: SelectFloatingContext is missing. Select parts must be placed within <Select.Root>.",
"62": "Base UI: SliderRootContext is missing. Slider parts must be placed within <Slider.Root>.",
"63": "Base UI: SwitchRootContext is missing. Switch parts must be placed within <Switch.Root>.",
"64": "Base UI: TabsRootContext is missing. Tabs parts must be placed within <Tabs.Root>.",
"65": "Base UI: TabsListContext is missing. TabsList parts must be placed within <Tabs.List>.",
"66": "Base UI: ToastRootContext is missing. Toast parts must be used within <Toast.Root>.",
"67": "Base UI: ToastViewportContext is missing. Toast parts must be placed within <Toast.Viewport>.",
"68": "Base UI: ToolbarGroupContext is missing. ToolbarGroup parts must be placed within <Toolbar.Group>.",
"69": "Base UI: ToolbarRootContext is missing. Toolbar parts must be placed within <Toolbar.Root>.",
"70": "Base UI: <Tooltip.Portal> is missing.",
"71": "Base UI: TooltipPositionerContext is missing. TooltipPositioner parts must be placed within <Tooltip.Positioner>.",
"72": "Base UI: TooltipRootContext is missing. Tooltip parts must be placed within <Tooltip.Root>.",
"73": "Base UI: useToastManager must be used within <Toast.Provider>.",
"74": "Base UI: must be either used within a component or provided with a handle.",
"75": "Base UI: PopoverTrigger must have an id prop specified.",
"76": "Base UI: selectors are required to call useState.",
"77": "Base UI: Trigger must have an id prop specified.",
"78": "Base UI: <AlertDialog.Trigger> must be used within <AlertDialog.Root> or provided with a handle.",
"79": "Base UI: <Dialog.Trigger> must be used within <Dialog.Root> or provided with a handle.",
"80": "Base UI: PopoverHandle.open: No trigger found with id "%s".",
"81": "Base UI: TooltipHandle.open: No trigger found with id "%s".",
"82": "Base UI: <Tooltip.Trigger> must be either used within a <Tooltip.Root> component or provided with a handle.",
"83": "Base UI: MenuHandle.open: No trigger found with id "%s".",
"84": "Base UI: ToastPositionerContext is missing. ToastPositioner parts must be placed within <Toast.Positioner>.",
"85": "Base UI: <Menu.Trigger> must be either used within a <Menu.Root> component or provided with a handle.",
"86": "Base UI: FieldsetRootContext is missing. Fieldset parts must be placed within <Fieldset.Root>.",
"87": "Base UI: A trigger element cannot be registered under multiple IDs in PopupTriggerMap.",
"88": "Base UI: PreviewCardHandle.open: No trigger found with id "%s".",
"89": "Base UI: must be either used within a component or provided with a handle.",
"90": "Base UI: DrawerRootContext is missing. Drawer parts must be placed within <Drawer.Root>.",
"91": "Base UI: DrawerProviderContext is missing. Use <Drawer.Provider>.",
"92": "Base UI: DrawerViewportContext is missing. Drawer parts must be placed within <Drawer.Viewport>.",
"93": "Base UI: TemporalAdapterContext is missing. Temporal components must be place within ",
"94": "Base UI: LocalizationContext is missing. Temporal components must be place within ",
"95": "Base UI: SharedCalendarDayGridBodyContext is missing. <Calendar.DayGridRow /> must be placed within <Calendar.DayGridBody /> and <RangeCalendar.DayGridRow /> must be placed within <RangeCalendar.DayGridBody />.",
"96": "Base UI: SharedCalendarDayGridCellContext is missing. <Calendar.DayButton /> must be placed within <Calendar.DayGridCell /> and <RangeCalendar.DayButton /> must be placed within <RangeCalendar.DayGridCell />.",
"97": "Base UI: SharedCalendarRootContext is missing. Calendar parts must be placed within <Calendar.Root /> and Range Calendar parts must be placed within <RangeCalendar.Root />.",
"98": "Base UI: OTPFieldRootContext is missing. OTPField parts must be placed within <OTPField.Root>.",
"99": "Base UI: %sHandle.open() was called with the trigger id "%s", but no matching trigger is registered with this handle. An anchored popup cannot open without a trigger to anchor to. Pass the id of a mounted %s.Trigger that has this handle set on its "handle" prop.",
"100": "Base UI: the items prop received an object that is not a collection, so its items cannot be read. Pass an array of items, an array of groups with items, or the result of createItems(). See https://base-ui.com/react/components/combobox#createitems",
"101": "Base UI: SelectRootPropsContext is missing. Select parts must be placed within <Select.Root>.",
"103": "Base UI: Filter parts are missing their filter context and cannot access the query or items. Wrap the component root in its filter provider.",
"104": "Base UI: <Menu.%s> must be placed in a menu wrapped in <Menu.FilterProvider>. It reads the filter query and the matching items from the provider, which a plain menu does not have. Wrap the <Menu.Root> or <Menu.SubmenuRoot> it belongs to in <Menu.FilterProvider>. See https://base-ui.com/react/components/menu#filtering"
}

Src App Robots (`docs/src/app/robots.txt`)

Algolia-Crawler-Verif: 98C49CAFF7AEED76

User-agent: *
Allow: /

Disallow: /experiments/
Disallow: /hydration-repro/
Disallow: /playground/
Disallow: /docs-theme/

Src Blocks README (`docs/src/blocks/README.txt`)

This directory houses unstyled building blocks for the docs.

Src App (Docs) Production Error Page (`docs/src/app/(docs)/production-error/page.mdx`)

import ErrorCode from './ErrorCode';
import ErrorDisplay from './ErrorDisplay';

Production error #

Explanation for minified production error message.

A minified Base UI error occurred in the production build of React.

The full error message:

Src App (Docs) React Page (`docs/src/app/(docs)/react/page.mdx`)

React

Overview

No description available

Outline

  • Sections:
    • Quick start
    • Accessibility
    • Releases
    • Community
    • About Base UI

Read more

Handbook

No description available

Outline

  • Sections:
    • Styling
    • Animation
    • Composition
    • Customization
    • Forms
    • TypeScript

Read more

Components

No description available

Outline

  • Sections:
    • Accordion
    • Alert Dialog
    • Autocomplete
    • Avatar
    • Button
    • Checkbox
    • Checkbox Group
    • Collapsible
    • Combobox
    • Context Menu
    • Dialog
    • Drawer
    • Field
    • Fieldset
    • Form
    • Input
    • Menu
    • Menubar
    • Meter
    • Navigation Menu
    • Number Field
    • OTP Field
    • Popover
    • Preview Card
    • Progress
    • Radio Group
    • Scroll Area
    • Select
    • Separator
    • Slider
    • Switch
    • Tabs
    • Toast
    • Toggle
    • Toggle Group
    • Toolbar
    • Tooltip

Read more

Utils

No description available

Outline

  • Sections:
    • CSP Provider
    • Direction Provider
    • mergeProps
    • useRender

Read more

export const metadata =
/** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */ ({
robots: {
index: false,
},
other: {
audience: 'private',
},
});

Src App (Docs) React Components Page (`docs/src/app/(docs)/react/components/page.mdx`)

Components

Accordion

A set of collapsible panels with headings.

Outline

  • Keywords: React Accordion, Accordion Component, Collapsible Content, Expandable Panel, Accessible Accordion, Multi-Panel UI, Disclosure Widget, FAQ Component, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Open multiple panels
      • Hidden until found
    • API reference
      • Root
      • Item
      • Header
      • Trigger
      • Panel
  • Exports:
    • Accordion - Root
      • Props: className, defaultValue, disabled, hiddenUntilFound, keepMounted, loopFocus, multiple, onValueChange, orientation, render, style, value
      • Data Attributes: data-disabled, data-orientation
    • Accordion - Trigger
      • Props: className, nativeButton, render, style
      • Data Attributes: data-disabled, data-index, data-panel-open
    • Accordion - Item
      • Props: className, disabled, onOpenChange, render, style, value
      • Data Attributes: data-disabled, data-index, data-open
    • Accordion - Header
      • Props: className, render, style
      • Data Attributes: data-disabled, data-index, data-open
    • Accordion - Panel
      • Props: className, hiddenUntilFound, keepMounted, render, style
      • Data Attributes: data-disabled, data-ending-style, data-index, data-open, data-orientation, data-starting-style
      • CSS Variables: --accordion-panel-height, --accordion-panel-width
  • Types: Accordion.Header.Props, Accordion.Header.State, Accordion.Item.ChangeEventDetails, Accordion.Item.ChangeEventReason, Accordion.Item.Props, Accordion.Item.State, Accordion.Panel.Props, Accordion.Panel.State, Accordion.Root.ChangeEventDetails, Accordion.Root.ChangeEventReason, Accordion.Root.Props, Accordion.Root.State, Accordion.Root.Value, Accordion.Trigger.Props, Accordion.Trigger.State

Read more

Alert Dialog

A dialog that requires a user response to proceed.

Outline

  • Keywords: React Alert Dialog, Alert Dialog Component, Confirmation Modal, Warning Dialog, Blocking Modal, Interrupt Dialog, Destructive Action Confirm, Accessible Dialog, Headless React Components, React UI Overlay, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Open from a menu
      • Close confirmation
      • Detached triggers
      • Multiple triggers
      • Controlled mode with multiple triggers
    • API reference
      • Root
      • Trigger
      • Portal
      • Backdrop
      • Viewport
      • Popup
      • Title
      • Description
      • Close
    • createHandle
      • Handle
  • Exports:
    • Alert Dialog - Root
      • Props: actionsRef, children, defaultOpen, defaultTriggerId, handle, onOpenChange, onOpenChangeComplete, open, triggerId
    • Alert Dialog - Trigger
      • Props: className, handle, id, nativeButton, payload, render, style
      • Data Attributes: data-disabled, data-popup-open
    • Alert Dialog - Portal
      • Props: className, container, keepMounted, render, style
    • Alert Dialog - Backdrop
      • Props: className, forceRender, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Alert Dialog - Popup
      • Props: className, finalFocus, initialFocus, render, style
      • Data Attributes: data-closed, data-ending-style, data-nested, data-nested-dialog-open, data-open, data-starting-style
      • CSS Variables: --nested-dialogs
    • Alert Dialog - Title
      • Props: className, render, style
    • Alert Dialog - Description
      • Props: className, render, style
    • Alert Dialog - Close
      • Props: className, nativeButton, render, style
      • Data Attributes: data-disabled
    • Alert Dialog - Viewport
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-nested, data-nested-dialog-open, data-open, data-starting-style
    • Alert Dialog - createHandle
    • Alert Dialog - Handle
  • Types: AlertDialog.Backdrop.Props, AlertDialog.Backdrop.State, AlertDialog.Close.Props, AlertDialog.Close.State, AlertDialog.Description.Props, AlertDialog.Description.State, AlertDialog.Popup.Props, AlertDialog.Popup.State, AlertDialog.Portal.Props, AlertDialog.Portal.State, AlertDialog.Root.Actions, AlertDialog.Root.ChangeEventDetails, AlertDialog.Root.ChangeEventReason, AlertDialog.Root.Props, AlertDialog.Root.State, AlertDialog.Title.Props, AlertDialog.Title.State, AlertDialog.Trigger.Props, AlertDialog.Trigger.State, AlertDialog.Viewport.Props, AlertDialog.Viewport.State

Read more

Autocomplete

An input that suggests options as you type.

Outline

  • Keywords: React Autocomplete, Autocomplete Component, Search Suggestions, Filterable Input, Async Autocomplete, Typeahead, Lookahead, Autosuggest, Incremental Search, Predictive Text, Search Input, Accessible Combobox, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Item values
    • Examples
      • Async search
      • Inline autocomplete
      • Grouped
      • Fuzzy matching
      • Limit results
      • Auto highlight
      • Command palette
      • Grid layout
      • Virtualized
        • Memoizing items
    • API reference
      • Root
      • Value
      • Input
      • InputGroup
      • Trigger
      • Icon
      • Clear
      • List
      • Portal
      • Backdrop
      • Positioner
      • Popup
      • Arrow
      • Status
      • Empty
      • Collection
      • Row
      • Item
      • Group
      • GroupLabel
      • Separator
    • useFilter
    • useFilteredItems
  • Exports:
    • Autocomplete - Root
      • Props: actionsRef, autoHighlight, children, defaultOpen, defaultValue, disabled, filter, filteredItems, form, grid, highlightItemOnHover, id, inline, inputRef, itemToStringValue, items, keepHighlight, limit, locale, loopFocus, modal, mode, name, onItemHighlighted, onOpenChange, onOpenChangeComplete, onValueChange, open, openOnInputClick, readOnly, required, submitOnItemClick, value, virtualized
    • Autocomplete - Trigger
      • Props: className, disabled, nativeButton, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-list-empty, data-popup-open, data-popup-side, data-pressed, data-readonly, data-required, data-touched, data-valid
    • Autocomplete - Value
      • Props: children
    • Autocomplete - Input
      • Props: className, disabled, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-list-empty, data-popup-open, data-popup-side, data-pressed, data-readonly, data-required, data-touched, data-valid
    • Autocomplete - Icon
      • Props: className, render, style
    • Autocomplete - Clear
      • Props: className, disabled, keepMounted, nativeButton, render, style
      • Data Attributes: data-disabled, data-ending-style, data-popup-open, data-starting-style, data-visible
    • Autocomplete - List
      • Props: children, className, render, style
    • Autocomplete - Portal
      • Props: className, container, keepMounted, render, style
    • Autocomplete - Backdrop
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Autocomplete - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-empty, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --transform-origin
    • Autocomplete - Popup
      • Props: className, finalFocus, initialFocus, render, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-empty, data-ending-style, data-open, data-side, data-starting-style
    • Autocomplete - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-open, data-side, data-uncentered
    • Autocomplete - Item
      • Props: children, className, disabled, index, nativeButton, onClick, render, style, value
      • Data Attributes: data-disabled, data-highlighted
    • Autocomplete - Group
      • Props: className, items, render, style
    • Autocomplete - GroupLabel
      • Props: className, render, style
    • Autocomplete - Separator
      • Props: className, orientation, render, style
      • Data Attributes: data-orientation
    • Autocomplete - Status
      • Props: className, render, style
    • Autocomplete - Empty
      • Props: className, render, style
    • Autocomplete - Collection
      • Props: children
    • Autocomplete - Row
      • Props: className, render, style
    • Autocomplete - InputGroup
      • Props: className, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-list-empty, data-popup-open, data-popup-side, data-pressed, data-readonly, data-touched, data-valid
    • Autocomplete - useFilter
      • Parameters: options
    • Autocomplete - useFilteredItems
  • Types: Autocomplete.Arrow.Props, Autocomplete.Arrow.State, Autocomplete.Backdrop.Props, Autocomplete.Backdrop.State, Autocomplete.Clear.Props, Autocomplete.Clear.State, Autocomplete.Collection.Props, Autocomplete.Collection.State, Autocomplete.Empty.Props, Autocomplete.Empty.State, Autocomplete.Group.Props, Autocomplete.Group.State, Autocomplete.GroupLabel.Props, Autocomplete.GroupLabel.State, Autocomplete.Icon.Props, Autocomplete.Icon.State, Autocomplete.Input.Props, Autocomplete.Input.State, Autocomplete.InputGroup.Props, Autocomplete.InputGroup.State, Autocomplete.Item.Props, Autocomplete.Item.State, Autocomplete.List.Props, Autocomplete.List.State, Autocomplete.Popup.Props, Autocomplete.Popup.State, Autocomplete.Portal.Props, Autocomplete.Portal.State, Autocomplete.Positioner.Props, Autocomplete.Positioner.State, Autocomplete.Root.Actions, Autocomplete.Root.ChangeEventDetails, Autocomplete.Root.ChangeEventReason, Autocomplete.Root.HighlightEventDetails, Autocomplete.Root.HighlightEventReason, Autocomplete.Root.OpenChangeEventDetails, Autocomplete.Root.Props, Autocomplete.Root.State, Autocomplete.Row.Props, Autocomplete.Row.State, Autocomplete.Separator.Props, Autocomplete.Separator.State, Autocomplete.Status.Props, Autocomplete.Status.State, Autocomplete.Trigger.Props, Autocomplete.Trigger.State, Autocomplete.Value.Props, Autocomplete.Value.State

Read more

Avatar

An easily stylable avatar component.

Outline

  • Keywords: React Avatar, Avatar Component, Profile Image UI, User Image, User Avatar, Profile Picture, Account Image, Profile Icon, Initials Fallback, Accessible Avatar, Headless React Components, Customizable Avatar, Base UI
  • Sections:
    • Anatomy
    • Optimized and lazy-loaded images
      • Stacking
      • Server rendering
    • API reference
      • Root
      • Image
      • Fallback
    • Additional types
  • Exports:
    • Avatar - Root
      • Props: className, render, style
    • Avatar - Image
      • Props: className, keepMounted, onLoadingStatusChange, render, style
      • Data Attributes: data-ending-style, data-error, data-loading, data-starting-style
    • Avatar - Fallback
      • Props: className, delay, render, style
  • Types: Avatar.Fallback.Props, Avatar.Fallback.State, Avatar.Image.Props, Avatar.Image.State, Avatar.Root.Props, Avatar.Root.State

Read more

Button

A button component that can be rendered as another tag or focusable when disabled.

Outline

  • Keywords: React Button, Button Component, Focusable Disabled Button, Custom Element Button, Clickable Element, Action Button, Submit Button, Accessible Button, Loading State Button, Button as Link, Link Button, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Rendering as another tag
      • Rendering links as buttons
      • Loading states
    • API reference
  • Exports:
    • Button
      • Props: className, focusableWhenDisabled, nativeButton, render, style
      • Data Attributes: data-disabled
  • Types: Button.Props, Button.State, ButtonDataAttributes

Read more

Checkbox

An easily stylable checkbox component.

Outline

  • Keywords: React Checkbox, Checkbox Component, Accessible Checkbox, Customizable Checkbox, Form Control Checkbox, Checkmark, Tick Box, Selection Control, Checkbox Input, Binary Input, Checked State, Indeterminate Checkbox, Tri-State Checkbox, Headless React Components, Input Indicator, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Labeling a checkbox
      • Rendering as a native button
      • Form integration
    • API reference
      • Root
      • Indicator
  • Exports:
    • Checkbox - Root
      • Props: checked, className, defaultChecked, disabled, form, id, indeterminate, inputRef, name, nativeButton, onCheckedChange, parent, readOnly, render, required, style, uncheckedValue, value
      • Data Attributes: data-checked, data-dirty, data-disabled, data-filled, data-focused, data-indeterminate, data-invalid, data-readonly, data-required, data-touched, data-unchecked, data-valid
    • Checkbox - Indicator
      • Props: className, keepMounted, render, style
      • Data Attributes: data-checked, data-dirty, data-disabled, data-ending-style, data-filled, data-focused, data-indeterminate, data-invalid, data-readonly, data-required, data-starting-style, data-touched, data-unchecked, data-valid
  • Types: Checkbox.Indicator.Props, Checkbox.Indicator.State, Checkbox.Root.ChangeEventDetails, Checkbox.Root.ChangeEventReason, Checkbox.Root.Props, Checkbox.Root.State

Read more

Checkbox Group

Provides shared state to a series of checkboxes.

Outline

  • Keywords: React Checkbox Group, Checkbox Group Component, Grouped Checkboxes, Multiple Selection, Checkbox List, Multi-Select Checkboxes, Parent Child Checkbox, Accessible Checkbox Group, Form Fieldset Control, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Labeling a checkbox group
      • Rendering as a native button
      • Form integration
      • Parent checkbox
      • Nested parent checkbox
    • API reference
  • Exports:
    • CheckboxGroup
      • Props: allValues, className, defaultValue, disabled, onValueChange, render, style, value
      • Data Attributes: data-disabled
  • Types: CheckboxGroup.ChangeEventDetails, CheckboxGroup.ChangeEventReason, CheckboxGroup.Props, CheckboxGroup.State, CheckboxGroupDataAttributes

Read more

Collapsible

A collapsible panel controlled by a button.

Outline

  • Keywords: React Collapsible, Collapsible Component, Expandable Panel, Toggle Panel Button, Disclosure Widget, Show/Hide Content, Accordion Item, Accessible Disclosure, Headless React Components, Collapsible Trigger Panel, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Hidden until found
    • API reference
      • Root
      • Trigger
      • Panel
  • Exports:
    • Collapsible - Root
      • Props: className, defaultOpen, disabled, onOpenChange, open, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Collapsible - Trigger
      • Props: className, nativeButton, render, style
      • Data Attributes: data-panel-open
    • Collapsible - Panel
      • Props: className, hiddenUntilFound, keepMounted, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
      • CSS Variables: --collapsible-panel-height, --collapsible-panel-width
  • Types: Collapsible.Panel.Props, Collapsible.Panel.State, Collapsible.Root.ChangeEventDetails, Collapsible.Root.ChangeEventReason, Collapsible.Root.Props, Collapsible.Root.State, Collapsible.Trigger.Props, Collapsible.Trigger.State

Read more

Combobox

An input combined with a list of predefined items to select.

Outline

  • Keywords: React Combobox, Combobox Component, Combo Box, Filterable Select, Searchable Dropdown, Editable Select, Typeahead Select, Autocomplete Dropdown, Tags Input, Chip Input, Token Input, Multi-Value Input, Multiple Select Combobox, Async Combobox, Accessible Combobox, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Item values
    • Examples
      • Typed wrapper component
      • Value selection with IDs
      • Multiple select
        • Keeping the filter after selection
      • Input inside popup
      • Grouped
      • Async search (single)
      • Async search (multiple)
      • Creatable
      • Virtualized
        • Memoizing items
    • API reference
      • Root
      • Label
      • Value
      • Icon
      • Input
      • InputGroup
      • Clear
      • Trigger
      • Chips
      • Chip
      • ChipRemove
      • List
      • Portal
      • Backdrop
      • Positioner
      • Popup
      • Arrow
      • Status
      • Empty
      • Collection
      • Row
      • Item
      • ItemIndicator
      • Group
      • GroupLabel
      • Separator
    • useFilter
    • useFilteredItems
    • createItems
  • Exports:
    • Combobox - Root
      • Props: actionsRef, autoComplete, autoHighlight, children, defaultInputValue, defaultOpen, defaultValue, disabled, filter, filteredItems, form, grid, highlightItemOnHover, id, inline, inputRef, inputValue, isItemEqualToValue, itemToStringLabel, itemToStringValue, items, limit, locale, loopFocus, modal, multiple, name, onInputValueChange, onItemHighlighted, onOpenChange, onOpenChangeComplete, onValueChange, open, openOnInputClick, readOnly, required, value, virtualized
    • Combobox - Trigger
      • Props: className, disabled, nativeButton, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-list-empty, data-placeholder, data-popup-open, data-popup-side, data-pressed, data-readonly, data-required, data-touched, data-valid
    • Combobox - Value
      • Props: children, placeholder
    • Combobox - Input
      • Props: className, disabled, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-list-empty, data-popup-open, data-popup-side, data-pressed, data-readonly, data-required, data-touched, data-valid
    • Combobox - Icon
      • Props: className, render, style
    • Combobox - Clear
      • Props: className, disabled, keepMounted, nativeButton, render, style
      • Data Attributes: data-disabled, data-ending-style, data-popup-open, data-starting-style, data-visible
    • Combobox - List
      • Props: children, className, render, style
    • Combobox - Portal
      • Props: className, container, keepMounted, render, style
    • Combobox - Backdrop
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Combobox - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-empty, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --transform-origin
    • Combobox - Popup
      • Props: className, finalFocus, initialFocus, render, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-empty, data-ending-style, data-open, data-side, data-starting-style
    • Combobox - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-open, data-side, data-uncentered
    • Combobox - Item
      • Props: children, className, disabled, index, nativeButton, onClick, render, style, value
      • Data Attributes: data-disabled, data-highlighted, data-selected
    • Combobox - Group
      • Props: className, items, render, style
    • Combobox - GroupLabel
      • Props: className, render, style
    • Combobox - Separator
      • Props: className, orientation, render, style
      • Data Attributes: data-orientation
    • Combobox - Label
      • Props: className, render, style
    • Combobox - Status
      • Props: className, render, style
    • Combobox - Empty
      • Props: className, render, style
    • Combobox - Collection
      • Props: children
    • Combobox - Row
      • Props: className, render, style
    • Combobox - Chips
      • Props: className, render, style
    • Combobox - Chip
      • Props: className, render, style
    • Combobox - ChipRemove
      • Props: className, nativeButton, render, style
    • Combobox - ItemIndicator
      • Props: children, className, keepMounted, render, style
      • Data Attributes: data-ending-style, data-starting-style
    • Combobox - createItems
      • Parameters: data, options
    • Combobox - InputGroup
      • Props: className, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-list-empty, data-placeholder, data-popup-open, data-popup-side, data-pressed, data-readonly, data-touched, data-valid
    • Combobox - useFilter
      • Parameters: options
    • Combobox - useFilteredItems
    • ComboboxItemCollection
  • Types: Combobox.Arrow.Props, Combobox.Arrow.State, Combobox.Backdrop.Props, Combobox.Backdrop.State, Combobox.Chip.Props, Combobox.Chip.State, Combobox.ChipRemove.Props, Combobox.ChipRemove.State, Combobox.Chips.Props, Combobox.Chips.State, Combobox.Clear.Props, Combobox.Clear.State, Combobox.Collection.Props, Combobox.Collection.State, Combobox.Empty.Props, Combobox.Empty.State, Combobox.Group.Props, Combobox.Group.State, Combobox.GroupLabel.Props, Combobox.GroupLabel.State, Combobox.Icon.Props, Combobox.Icon.State, Combobox.Input.Props, Combobox.Input.State, Combobox.InputGroup.Props, Combobox.InputGroup.State, Combobox.Item.Props, Combobox.Item.State, Combobox.ItemIndicator.Props, Combobox.ItemIndicator.State, Combobox.Label.Props, Combobox.Label.State, Combobox.List.Props, Combobox.List.State, Combobox.Popup.Props, Combobox.Popup.State, Combobox.Portal.Props, Combobox.Portal.State, Combobox.Positioner.Props, Combobox.Positioner.State, Combobox.Root.Actions, Combobox.Root.ChangeEventDetails, Combobox.Root.ChangeEventReason, Combobox.Root.HighlightEventDetails, Combobox.Root.HighlightEventReason, Combobox.Root.OpenChangeEventDetails, Combobox.Root.Props, Combobox.Root.State, Combobox.Row.Props, Combobox.Row.State, Combobox.Separator.Props, Combobox.Separator.State, Combobox.Status.Props, Combobox.Status.State, Combobox.Trigger.Props, Combobox.Trigger.State, Combobox.Value.Props, Combobox.Value.State

Read more

Context Menu

A menu that appears at the pointer on right click or long press.

Outline

  • Keywords: React Context Menu, Context Menu Component, Right Click Menu, Secondary Click Menu, Pointer Menu, Touch Hold Menu, Long Press Menu, Nested Menu React, Accessible Context Menu, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Using with Menu
      • Nested menu
    • API reference
      • Root
      • Trigger
      • Portal
      • Backdrop
      • Positioner
      • Popup
      • Arrow
      • Item
      • LinkItem
      • SubmenuRoot
      • SubmenuTrigger
      • Group
      • GroupLabel
      • RadioGroup
      • RadioItem
      • RadioItemIndicator
      • CheckboxItem
      • CheckboxItemIndicator
      • Separator
  • Exports:
    • Context Menu - Root
      • Props: actionsRef, children, defaultOpen, disabled, highlightItemOnHover, loopFocus, onItemHighlighted, onOpenChange, onOpenChangeComplete, open, orientation
    • Context Menu - Trigger
      • Props: className, render, style
      • Data Attributes: data-popup-open, data-pressed
    • Context Menu - Portal
      • Props: className, container, keepMounted, render, style
    • Context Menu - Backdrop
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Context Menu - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --positioner-height, --positioner-width, --transform-origin
    • Context Menu - Popup
      • Props: children, className, finalFocus, render, style
      • Data Attributes: data-align, data-closed, data-ending-style, data-instant, data-open, data-side, data-starting-style
    • Context Menu - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-open, data-side, data-uncentered
    • Context Menu - Item
      • Props: className, closeOnClick, disabled, label, nativeButton, onClick, render, style
      • Data Attributes: data-disabled, data-highlighted
    • Context Menu - Group
      • Props: children, className, render, style
    • Context Menu - GroupLabel
      • Props: className, render, style
    • Context Menu - Separator
      • Props: className, orientation, render, style
      • Data Attributes: data-orientation
    • Context Menu - SubmenuRoot
      • Props: actionsRef, children, closeParentOnEsc, defaultOpen, disabled, highlightItemOnHover, loopFocus, onItemHighlighted, onOpenChange, onOpenChangeComplete, open, orientation
    • Context Menu - SubmenuTrigger
      • Props: className, closeDelay, delay, disabled, label, nativeButton, onClick, openOnHover, render, style
      • Data Attributes: data-disabled, data-highlighted, data-popup-open
    • Context Menu - RadioGroup
      • Props: children, className, defaultValue, disabled, onValueChange, render, style, value
    • Context Menu - RadioItem
      • Props: className, closeOnClick, disabled, label, nativeButton, onClick, render, style, value
      • Data Attributes: data-checked, data-disabled, data-highlighted, data-unchecked
    • Context Menu - RadioItemIndicator
      • Props: className, keepMounted, render, style
      • Data Attributes: data-checked, data-disabled, data-ending-style, data-starting-style, data-unchecked
    • Context Menu - CheckboxItem
      • Props: checked, className, closeOnClick, defaultChecked, disabled, label, nativeButton, onCheckedChange, onClick, render, style
      • Data Attributes: data-checked, data-disabled, data-highlighted, data-unchecked
    • Context Menu - CheckboxItemIndicator
      • Props: className, keepMounted, render, style
      • Data Attributes: data-checked, data-disabled, data-ending-style, data-starting-style, data-unchecked
    • Context Menu - LinkItem
      • Props: className, closeOnClick, label, render, style
      • Data Attributes: data-highlighted
  • Types: ContextMenu.Arrow.Props, ContextMenu.Arrow.State, ContextMenu.Backdrop.Props, ContextMenu.Backdrop.State, ContextMenu.CheckboxItem.ChangeEventDetails, ContextMenu.CheckboxItem.ChangeEventReason, ContextMenu.CheckboxItem.Props, ContextMenu.CheckboxItem.State, ContextMenu.CheckboxItemIndicator.Props, ContextMenu.CheckboxItemIndicator.State, ContextMenu.Group.Props, ContextMenu.Group.State, ContextMenu.GroupLabel.Props, ContextMenu.GroupLabel.State, ContextMenu.Item.Props, ContextMenu.Item.State, ContextMenu.LinkItem.Props, ContextMenu.LinkItem.State, ContextMenu.Popup.Props, ContextMenu.Popup.State, ContextMenu.Portal.Props, ContextMenu.Portal.State, ContextMenu.Positioner.Props, ContextMenu.Positioner.State, ContextMenu.RadioGroup.ChangeEventDetails, ContextMenu.RadioGroup.ChangeEventReason, ContextMenu.RadioGroup.Props, ContextMenu.RadioGroup.State, ContextMenu.RadioItem.Props, ContextMenu.RadioItem.State, ContextMenu.RadioItemIndicator.Props, ContextMenu.RadioItemIndicator.State, ContextMenu.Root.Actions, ContextMenu.Root.ChangeEventDetails, ContextMenu.Root.ChangeEventReason, ContextMenu.Root.Props, ContextMenu.Root.State, ContextMenu.Separator.Props, ContextMenu.Separator.State, ContextMenu.SubmenuRoot.ChangeEventDetails, ContextMenu.SubmenuRoot.ChangeEventReason, ContextMenu.SubmenuRoot.Props, ContextMenu.SubmenuRoot.State, ContextMenu.SubmenuTrigger.Props, ContextMenu.SubmenuTrigger.State, ContextMenu.Trigger.Props, ContextMenu.Trigger.State

Read more

Dialog

A popup that opens on top of the entire page.

Outline

  • Keywords: React Dialog, Modal Dialog Component, Modal Popup, Modal Window, Popup Window, Modal Overlay, Overlay, Lightbox, Popover Dialog, Controlled Dialog State, Nested Dialog React, Focus Trap Dialog, Accessible Dialog, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • State
      • Open from a menu
      • Nested dialogs
      • Close confirmation
      • Custom focus management
      • Outside scroll dialog
      • Inside scroll dialog
      • Placing elements outside the popup
      • Detached triggers
      • Multiple triggers
      • Controlled mode with multiple triggers
    • API reference
      • Root
      • Trigger
      • Portal
      • Backdrop
      • Viewport
      • Popup
      • Title
      • Description
      • Close
    • createHandle
      • Handle
  • Exports:
    • Dialog - Root
      • Props: actionsRef, children, defaultOpen, defaultTriggerId, disablePointerDismissal, handle, modal, onOpenChange, onOpenChangeComplete, open, triggerId
    • Dialog - Trigger
      • Props: className, handle, id, nativeButton, payload, render, style
      • Data Attributes: data-disabled, data-popup-open
    • Dialog - Portal
      • Props: className, container, keepMounted, render, style
    • Dialog - Backdrop
      • Props: className, forceRender, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Dialog - Popup
      • Props: className, finalFocus, initialFocus, render, style
      • Data Attributes: data-closed, data-ending-style, data-nested, data-nested-dialog-open, data-open, data-starting-style
      • CSS Variables: --nested-dialogs
    • Dialog - Title
      • Props: className, render, style
    • Dialog - Description
      • Props: className, render, style
    • Dialog - Close
      • Props: className, nativeButton, render, style
      • Data Attributes: data-disabled
    • Dialog - Viewport
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-nested, data-nested-dialog-open, data-open, data-starting-style
    • Dialog - createHandle
    • Dialog - Handle
  • Types: Dialog.Backdrop.Props, Dialog.Backdrop.State, Dialog.Close.Props, Dialog.Close.State, Dialog.Description.Props, Dialog.Description.State, Dialog.Popup.Props, Dialog.Popup.State, Dialog.Portal.Props, Dialog.Portal.State, Dialog.Root.Actions, Dialog.Root.ChangeEventDetails, Dialog.Root.ChangeEventReason, Dialog.Root.Props, Dialog.Root.State, Dialog.Title.Props, Dialog.Title.State, Dialog.Trigger.Props, Dialog.Trigger.State, Dialog.Viewport.Props, Dialog.Viewport.State

Read more

Drawer

A panel that slides in from the edge of the screen.

Outline

  • Keywords: React Drawer, Drawer Component, Side Panel, Bottom Sheet, Swipe Dismiss Drawer, Offcanvas, Sliding Panel, Modal Drawer, Controlled Drawer State, Accessible Drawer, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • State
      • Position
      • Nested drawers
      • Snap points
      • Virtual keyboard aware
      • Indent effect
      • Non-modal
      • Mobile navigation
      • Swipe to open
      • Close confirmation
      • Action sheet with separate destructive action
      • Detached triggers
      • Stacking and animations
    • API reference
      • Provider
      • IndentBackground
      • Indent
      • Root
      • Trigger
      • SwipeArea
      • VirtualKeyboardProvider
      • Portal
      • Backdrop
      • Viewport
      • Popup
      • Content
      • Title
      • Description
      • Close
    • createHandle
      • Handle
  • Exports:
    • Drawer - Root
      • Props: actionsRef, children, defaultOpen, defaultSnapPoint, defaultTriggerId, disablePointerDismissal, handle, modal, onOpenChange, onOpenChangeComplete, onSnapPointChange, open, snapPoint, snapPoints, snapToSequentialPoints, swipeDirection, triggerId
    • Drawer - Provider
      • Props: children
    • Drawer - Trigger
      • Props: className, handle, id, nativeButton, payload, render, style
      • Data Attributes: data-disabled, data-popup-open
    • Drawer - Portal
      • Props: className, container, keepMounted, render, style
    • Drawer - Backdrop
      • Props: className, forceRender, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
      • CSS Variables: --drawer-swipe-progress
    • Drawer - Popup
      • Props: className, finalFocus, initialFocus, render, style
      • Data Attributes: data-closed, data-ending-style, data-expanded, data-nested-drawer-open, data-nested-drawer-swiping, data-open, data-starting-style, data-swipe-direction, data-swipe-dismiss, data-swiping
      • CSS Variables: --drawer-frontmost-height, --drawer-height, --drawer-snap-point-offset, --drawer-swipe-movement-x, --drawer-swipe-movement-y, --drawer-swipe-strength, --nested-drawers
    • Drawer - Content
      • Props: className, render, style
    • Drawer - Title
      • Props: className, render, style
    • Drawer - Description
      • Props: className, render, style
    • Drawer - Close
      • Props: className, nativeButton, render, style
      • Data Attributes: data-disabled
    • Drawer - Viewport
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-nested, data-open, data-starting-style
      • CSS Variables: --drawer-keyboard-inset
    • Drawer - createHandle
    • Drawer - Handle
    • Drawer - Indent
      • Props: className, render, style
    • Drawer - IndentBackground
      • Props: className, render, style
    • Drawer - SwipeArea
      • Props: className, disabled, render, style, swipeDirection
      • Data Attributes: data-closed, data-disabled, data-open, data-swipe-direction, data-swiping
    • Drawer - VirtualKeyboardProvider
      • Props: children
  • Types: Drawer.Backdrop.Props, Drawer.Backdrop.State, Drawer.Close.Props, Drawer.Close.State, Drawer.Content.Props, Drawer.Content.State, Drawer.Description.Props, Drawer.Description.State, Drawer.Indent.Props, Drawer.Indent.State, Drawer.IndentBackground.Props, Drawer.IndentBackground.State, Drawer.Popup.Props, Drawer.Popup.State, Drawer.Portal.Props, Drawer.Portal.State, Drawer.Provider.Props, Drawer.Provider.State, Drawer.Root.Actions, Drawer.Root.ChangeEventDetails, Drawer.Root.ChangeEventReason, Drawer.Root.Props, Drawer.Root.SnapPoint, Drawer.Root.SnapPointChangeEventDetails, Drawer.Root.SnapPointChangeEventReason, Drawer.Root.State, Drawer.SwipeArea.Props, Drawer.SwipeArea.State, Drawer.Title.Props, Drawer.Title.State, Drawer.Trigger.Props, Drawer.Trigger.State, Drawer.Viewport.Props, Drawer.Viewport.State, Drawer.VirtualKeyboardProvider.Props, Drawer.VirtualKeyboardProvider.State

Read more

Field

A component that provides labeling and validation for form controls.

Outline

  • Keywords: React Field Component, Form Field Labeling, Form Label, Input Wrapper, Form Validation, Accessible Form Field, Field Validation UI, Headless React Components, Custom Form Control Wrapper, Form Description Error State, Base UI
  • Sections:
    • Anatomy
    • API reference
      • Root
      • Label
      • Control
      • Description
      • Item
      • Error
      • Validity
  • Exports:
    • Field - Root
      • Props: actionsRef, className, dirty, disabled, invalid, name, render, style, touched, validate, validationDebounceTime, validationMode
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-touched, data-valid
    • Field - Item
      • Props: className, disabled, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-touched, data-valid
    • Field - Description
      • Props: className, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-touched, data-valid
    • Field - Control
      • Props: className, defaultValue, onValueChange, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-touched, data-valid
    • Field - Label
      • Props: className, nativeLabel, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-touched, data-valid
    • Field - Error
      • Props: className, match, render, style
      • Data Attributes: data-dirty, data-disabled, data-ending-style, data-filled, data-focused, data-invalid, data-starting-style, data-touched, data-valid
    • Field - Validity
      • Props: children
  • Types: Field.Control.ChangeEventDetails, Field.Control.ChangeEventReason, Field.Control.Props, Field.Control.State, Field.Description.Props, Field.Description.State, Field.Error.Props, Field.Error.State, Field.Item.Props, Field.Item.State, Field.Label.Props, Field.Label.State, Field.Root.Actions, Field.Root.Props, Field.Root.State, Field.Validity.Props, Field.Validity.State

Read more

Fieldset

A native fieldset element with an easily stylable legend.

Outline

  • Keywords: React Fieldset, Fieldset Component, Form Field Grouping, Form Fieldset, Form Group, Input Grouping, Custom Legend Styling, Fieldset Legend, Accessible Fieldset, Headless React Components, Form Section Labeling, Base UI
  • Sections:
    • Anatomy
    • API reference
      • Root
      • Legend
  • Exports:
    • Fieldset - Root
      • Props: className, render, style
    • Fieldset - Legend
      • Props: className, render, style
      • Data Attributes: data-disabled
  • Types: Fieldset.Legend.Props, Fieldset.Legend.State, Fieldset.Root.Props, Fieldset.Root.State

Read more

Form

A native form element with consolidated error handling.

Outline

  • Keywords: React Form Component, Form Submission Handler, Form Validation, Form State, Server Function Form, JavaScript Form Values, Accessible Form, Headless React Components, Form Error Handling, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Submit with a Server Function
      • Submit form values as a JavaScript object
      • Using with Zod
    • API reference
  • Exports:
    • Form
      • Props: actionsRef, className, errors, onFormSubmit, render, style, validationMode
  • Types: Form.Actions, Form.Props, Form.State, Form.SubmitEventDetails, Form.SubmitEventReason, Form.ValidationMode, Form.Values

Read more

Input

A native input element that automatically works with Field.

Outline

  • Keywords: React Input, Input Component, Input Field, Form Input Field, Text Field, Text Input, Text Box, Form Input, Textarea Alternative, Controlled Input, Form Element, Accessible Input, Headless React Components, Unstyled Input, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • API reference
  • Exports:
    • Input
      • Props: className, defaultValue, onValueChange, render, style, value
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-touched, data-valid
  • Types: Input.ChangeEventDetails, Input.ChangeEventReason, Input.Props, Input.State, InputDataAttributes

Read more

A list of actions in a dropdown, enhanced with keyboard navigation.

Outline

  • Keywords: React Menu, Menu Component, Dropdown Menu, Dropdown Actions, Command Menu, Action List, Keyboard Navigation Menu, Roving Tabindex Menu, Nested Menu React, Flyout Menu, Context Actions, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Open on hover
      • Checkbox items
      • Radio items
      • Close on click
      • Group labels
      • Nested menu
      • Navigate to another page
      • Open a dialog
      • Detached triggers
      • Multiple triggers
      • Controlled mode with multiple triggers
      • Arrow
      • Animating the Menu
        • Position and Size
        • Content
      • Filtering [Preview]
        • Matching items
        • Controlling the query
        • Highlighting
        • Focus and keyboard
        • Submenus
        • Filtering with detached triggers
    • API reference
      • FilterProvider [Preview]
      • Root
      • Trigger
      • Portal
      • Backdrop
      • Positioner
      • Popup
      • Viewport
      • Arrow
      • Input
      • Clear
      • Empty
      • List
      • Item
      • LinkItem
      • SubmenuRoot
      • SubmenuTrigger
      • Group
      • GroupLabel
      • RadioGroup
      • RadioItem
      • RadioItemIndicator
      • CheckboxItem
      • CheckboxItemIndicator
      • Separator
    • useFilter
    • createHandle
      • Handle
  • Exports:
    • Menu - Root
      • Props: actionsRef, children, closeParentOnEsc, defaultOpen, defaultTriggerId, disabled, handle, highlightItemOnHover, loopFocus, modal, onItemHighlighted, onOpenChange, onOpenChangeComplete, open, orientation, triggerId
    • Menu - Trigger
      • Props: children, className, closeDelay, delay, disabled, handle, nativeButton, openOnHover, payload, render, style
      • Data Attributes: data-disabled, data-popup-open, data-pressed
    • Menu - Input
      • Props: className, render, style
      • Data Attributes: data-highlighted
    • Menu - Clear
      • Props: className, disabled, nativeButton, render, style
      • Data Attributes: data-disabled
    • Menu - List
      • Props: className, render, style
    • Menu - Portal
      • Props: className, container, keepMounted, render, style
    • Menu - Backdrop
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Menu - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --positioner-height, --positioner-width, --transform-origin
    • Menu - Popup
      • Props: children, className, finalFocus, render, style
      • Data Attributes: data-align, data-closed, data-ending-style, data-instant, data-open, data-side, data-starting-style
    • Menu - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-open, data-side, data-uncentered
    • Menu - Item
      • Props: className, closeOnClick, disabled, label, nativeButton, onClick, render, style
      • Data Attributes: data-disabled, data-highlighted
    • Menu - Viewport
      • Props: children, className, render, style
      • Data Attributes: data-activation-direction, data-current, data-instant, data-previous, data-transitioning
      • CSS Variables: --popup-height, --popup-width
    • Menu - Group
      • Props: children, className, render, style
    • Menu - GroupLabel
      • Props: className, render, style
    • Menu - Separator
      • Props: className, orientation, render, style
      • Data Attributes: data-orientation
    • Menu - Empty
      • Props: className, render, style
    • Menu - SubmenuRoot
      • Props: actionsRef, children, closeParentOnEsc, defaultOpen, disabled, highlightItemOnHover, loopFocus, onItemHighlighted, onOpenChange, onOpenChangeComplete, open, orientation
    • Menu - SubmenuTrigger
      • Props: className, closeDelay, delay, disabled, label, nativeButton, onClick, openOnHover, render, style
      • Data Attributes: data-disabled, data-highlighted, data-popup-open
    • Menu - RadioGroup
      • Props: children, className, defaultValue, disabled, onValueChange, render, style, value
    • Menu - RadioItem
      • Props: className, closeOnClick, disabled, label, nativeButton, onClick, render, style, value
      • Data Attributes: data-checked, data-disabled, data-highlighted, data-unchecked
    • Menu - RadioItemIndicator
      • Props: className, keepMounted, render, style
      • Data Attributes: data-checked, data-disabled, data-ending-style, data-starting-style, data-unchecked
    • Menu - CheckboxItem
      • Props: checked, className, closeOnClick, defaultChecked, disabled, label, nativeButton, onCheckedChange, onClick, render, style
      • Data Attributes: data-checked, data-disabled, data-highlighted, data-unchecked
    • Menu - CheckboxItemIndicator
      • Props: className, keepMounted, render, style
      • Data Attributes: data-checked, data-disabled, data-ending-style, data-starting-style, data-unchecked
    • Menu - createHandle
    • Menu - FilterProvider
      • Props: autoHighlight, children, defaultValue, filter, locale, onValueChange, value
    • Menu - Handle
    • Menu - LinkItem
      • Props: className, closeOnClick, label, render, style
      • Data Attributes: data-highlighted
    • Menu - useFilter
      • Parameters: options
  • Types: Menu.Arrow.Props, Menu.Arrow.State, Menu.Backdrop.Props, Menu.Backdrop.State, Menu.CheckboxItem.ChangeEventDetails, Menu.CheckboxItem.ChangeEventReason, Menu.CheckboxItem.Props, Menu.CheckboxItem.State, Menu.CheckboxItemIndicator.Props, Menu.CheckboxItemIndicator.State, Menu.Clear.Props, Menu.Clear.State, Menu.Empty.Props, Menu.Empty.State, Menu.FilterProvider.ChangeEventDetails, Menu.FilterProvider.ChangeEventReason, Menu.FilterProvider.Props, Menu.FilterProvider.State, Menu.Group.Props, Menu.Group.State, Menu.GroupLabel.Props, Menu.GroupLabel.State, Menu.Input.Props, Menu.Input.State, Menu.Item.Props, Menu.Item.State, Menu.LinkItem.Props, Menu.LinkItem.State, Menu.List.Props, Menu.List.State, Menu.Popup.Props, Menu.Popup.State, Menu.Portal.Props, Menu.Portal.State, Menu.Positioner.Props, Menu.Positioner.State, Menu.RadioGroup.ChangeEventDetails, Menu.RadioGroup.ChangeEventReason, Menu.RadioGroup.Props, Menu.RadioGroup.State, Menu.RadioItem.Props, Menu.RadioItem.State, Menu.RadioItemIndicator.Props, Menu.RadioItemIndicator.State, Menu.Root.Actions, Menu.Root.ChangeEventDetails, Menu.Root.ChangeEventReason, Menu.Root.HighlightEventDetails, Menu.Root.HighlightEventReason, Menu.Root.Orientation, Menu.Root.Props, Menu.Root.State, Menu.Separator.Props, Menu.Separator.State, Menu.SubmenuRoot.ChangeEventDetails, Menu.SubmenuRoot.ChangeEventReason, Menu.SubmenuRoot.Props, Menu.SubmenuRoot.State, Menu.SubmenuTrigger.Props, Menu.SubmenuTrigger.State, Menu.Trigger.Props, Menu.Trigger.State, Menu.Viewport.Props, Menu.Viewport.State

Read more

A menu bar providing commands and options for your application.

Outline

  • Keywords: React Menubar, Menubar Component, Application Menu Bar, App Menu, Navigation Bar, Command Bar, Desktop Style Menu, Keyboard Navigation Menu, Accessible Menubar, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • API reference
  • Exports:
    • Menubar
      • Props: className, disabled, loopFocus, modal, orientation, render, style
      • Data Attributes: data-has-submenu-open, data-modal, data-orientation
  • Types: Menubar.Props, Menubar.State, MenubarDataAttributes

Read more

Meter

A graphical display of a numeric value within a range.

Outline

  • Keywords: React Meter, Meter Component, Progress Meter, Gauge, Level Indicator, Measurement Display, Capacity Indicator, Value Indicator, Rating Meter, Fuel Gauge, Accessible Meter, Headless React Components, Graphical Value Display, Base UI
  • Sections:
    • Anatomy
    • API reference
      • Root
      • Track
      • Indicator
      • Value
      • Label
  • Exports:
    • Meter - Root
      • Props: aria-valuetext, className, format, getAriaValueText, locale, max, min, render, style, value
    • Meter - Value
      • Props: children, className, render, style
    • Meter - Indicator
      • Props: className, render, style
    • Meter - Track
      • Props: className, render, style
    • Meter - Label
      • Props: className, render, style
  • Types: Meter.Indicator.Props, Meter.Indicator.State, Meter.Label.Props, Meter.Label.State, Meter.Root.Props, Meter.Root.State, Meter.Track.Props, Meter.Track.State, Meter.Value.Props, Meter.Value.State

Read more

A collection of links and menus for website navigation.

Outline

  • Keywords: React Navigation Menu, Navigation Menu Component, Mega Menu React, Dropdown Nav, Flyout Menu, Site Navigation, Navbar, Header Menu, Multi Level Navigation, Custom Link Menu, Scrollable Navigation Menu, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Nested submenus
      • Nested inline submenus
      • Custom links
      • Large menus
    • Closing animations
    • API reference
      • Root
      • List
      • Item
      • Trigger
      • Icon
      • Content
      • Link
      • Backdrop
      • Portal
      • Positioner
      • Popup
      • Viewport
      • Arrow
  • Exports:
    • Navigation Menu - Root
      • Props: actionsRef, className, closeDelay, defaultValue, delay, onOpenChangeComplete, onValueChange, orientation, render, style, value
    • Navigation Menu - Trigger
      • Props: className, disabled, nativeButton, render, style
      • Data Attributes: data-disabled, data-popup-open, data-pressed
    • Navigation Menu - Icon
      • Props: className, render, style
      • Data Attributes: data-popup-open
    • Navigation Menu - List
      • Props: className, render, style
    • Navigation Menu - Portal
      • Props: className, container, keepMounted, render, style
    • Navigation Menu - Backdrop
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Navigation Menu - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-instant, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --positioner-height, --positioner-width, --transform-origin
    • Navigation Menu - Popup
      • Props: className, render, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-ending-style, data-open, data-side, data-starting-style
      • CSS Variables: --popup-height, --popup-width
    • Navigation Menu - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-open, data-side, data-uncentered
    • Navigation Menu - Item
      • Props: className, render, style, value
    • Navigation Menu - Content
      • Props: className, keepMounted, render, style
      • Data Attributes: data-activation-direction, data-closed, data-ending-style, data-open, data-starting-style
    • Navigation Menu - Viewport
      • Props: className, render, style
    • Navigation Menu - Link
      • Props: active, className, closeOnClick, render, style
      • Data Attributes: data-active
  • Types: NavigationMenu.Arrow.Props, NavigationMenu.Arrow.State, NavigationMenu.Backdrop.Props, NavigationMenu.Backdrop.State, NavigationMenu.Content.Props, NavigationMenu.Content.State, NavigationMenu.Icon.Props, NavigationMenu.Icon.State, NavigationMenu.Item.Props, NavigationMenu.Item.State, NavigationMenu.Link.Props, NavigationMenu.Link.State, NavigationMenu.List.Props, NavigationMenu.List.State, NavigationMenu.Popup.Props, NavigationMenu.Popup.State, NavigationMenu.Portal.Props, NavigationMenu.Portal.State, NavigationMenu.Positioner.Props, NavigationMenu.Positioner.State, NavigationMenu.Root.Actions, NavigationMenu.Root.ChangeEventDetails, NavigationMenu.Root.ChangeEventReason, NavigationMenu.Root.Props, NavigationMenu.Root.State, NavigationMenu.Root.Value, NavigationMenu.Trigger.Props, NavigationMenu.Trigger.State, NavigationMenu.Viewport.Props, NavigationMenu.Viewport.State

Read more

Number Field

A numeric input element with increment and decrement buttons, and a scrub area.

Outline

  • Keywords: React Number Field, Number Input Component, Number Spinner, Spinner Input, Spin Button, Stepper, Numeric Input, Increment Decrement Buttons, Up Down Control, Scrub Area Input, Numeric Form Control, Accessible Number Field, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • API reference
      • Root
      • ScrubArea
      • ScrubAreaCursor
      • Group
      • Decrement
      • Input
      • Increment
  • Exports:
    • Number Field - Root
      • Props: allowOutOfRange, allowWheelScrub, className, defaultValue, disabled, form, format, id, inputRef, largeStep, locale, max, min, name, onValueChange, onValueCommitted, readOnly, render, required, smallStep, snapOnStep, step, style, value
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
    • Number Field - Input
      • Props: aria-roledescription, className, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
    • Number Field - Group
      • Props: className, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
    • Number Field - ScrubArea
      • Props: className, direction, pixelSensitivity, render, style, teleportDistance
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
    • Number Field - ScrubAreaCursor
      • Props: className, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
    • Number Field - Decrement
      • Props: className, nativeButton, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
    • Number Field - Increment
      • Props: className, nativeButton, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
  • Types: NumberField.Decrement.Props, NumberField.Decrement.State, NumberField.Group.Props, NumberField.Group.State, NumberField.Increment.Props, NumberField.Increment.State, NumberField.Input.Props, NumberField.Input.State, NumberField.Root.ChangeEventDetails, NumberField.Root.ChangeEventReason, NumberField.Root.CommitEventDetails, NumberField.Root.CommitEventReason, NumberField.Root.Props, NumberField.Root.State, NumberField.ScrubArea.Props, NumberField.ScrubArea.State, NumberField.ScrubAreaCursor.Props, NumberField.ScrubAreaCursor.State

Read more

OTP Field

A one-time password input composed of individual character slots.

Outline

  • Keywords: React OTP Field, One-Time Password Input, Verification Code Input, OTP Input Component, Pin Input, Passcode Input, Two-Factor Authentication Input, 2FA Input, Multi-Slot Input, Accessible OTP Field, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Labeling an OTP field
      • Form integration
      • Alphanumeric verification codes
      • Grouped layouts
      • Placeholder hints
      • Custom normalization
      • Masked entry
    • API reference
      • Root
      • Input
      • Separator
  • Exports:
    • OTP Field - Root
      • Props: autoComplete, autoSubmit, className, defaultValue, disabled, form, id, inputMode, length, mask, name, normalizeValue, onValueChange, onValueComplete, onValueInvalid, readOnly, render, required, style, validationType, value
      • Data Attributes: data-complete, data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-touched, data-valid
    • OTP Field - Input
      • Props: className, render, style
      • Data Attributes: data-complete, data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-touched, data-valid
    • OTP Field - Separator
      • Props: className, orientation, render, style
      • Data Attributes: data-orientation
  • Types: OTPField.Input.Props, OTPField.Input.State, OTPField.Root.ChangeEventDetails, OTPField.Root.ChangeEventReason, OTPField.Root.CompleteEventDetails, OTPField.Root.CompleteEventReason, OTPField.Root.InvalidEventDetails, OTPField.Root.InvalidEventReason, OTPField.Root.Props, OTPField.Root.State, OTPField.Root.ValidationType, OTPField.Separator.Props, OTPField.Separator.State

Read more

Popover

An accessible popup anchored to a button.

Outline

  • Keywords: React Popover, Popover Component, Popover Menu, Popup Menu, Anchored Popup, Dropdown, Overlay, Floating Panel, Tooltip Alternative, Info Box, Callout, Popup Content, Detached Trigger Popover, Multi Trigger Popover, Hover Trigger Popover, Click Trigger Popover, Focus Trigger Popover, Animated Popover, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Opening on hover
      • Detached triggers
      • Multiple triggers
      • Controlled mode with multiple triggers
      • Animating the Popover
        • Position and Size
        • Content
    • API reference
      • Root
      • Trigger
      • Backdrop
      • Portal
      • Positioner
      • Popup
      • Arrow
      • Title
      • Description
      • Close
      • Viewport
    • createHandle
      • Handle
  • Exports:
    • Popover - Root
      • Props: actionsRef, children, defaultOpen, defaultTriggerId, handle, modal, onOpenChange, onOpenChangeComplete, open, triggerId
    • Popover - Trigger
      • Props: className, closeDelay, delay, handle, id, nativeButton, openOnHover, payload, render, style
      • Data Attributes: data-disabled, data-popup-open, data-pressed
    • Popover - Portal
      • Props: className, container, keepMounted, render, style
    • Popover - Backdrop
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Popover - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --positioner-height, --positioner-width, --transform-origin
    • Popover - Popup
      • Props: className, finalFocus, initialFocus, render, style
      • Data Attributes: data-align, data-closed, data-ending-style, data-instant, data-open, data-side, data-starting-style
      • CSS Variables: --popup-height, --popup-width
    • Popover - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-open, data-side, data-uncentered
    • Popover - Title
      • Props: className, render, style
    • Popover - Description
      • Props: className, render, style
    • Popover - Close
      • Props: className, nativeButton, render, style
    • Popover - Viewport
      • Props: children, className, render, style
      • Data Attributes: data-activation-direction, data-current, data-instant, data-previous, data-transitioning
      • CSS Variables: --popup-height, --popup-width
    • Popover - createHandle
    • Popover - Handle
  • Types: Popover.Arrow.Props, Popover.Arrow.State, Popover.Backdrop.Props, Popover.Backdrop.State, Popover.Close.Props, Popover.Close.State, Popover.Description.Props, Popover.Description.State, Popover.Popup.Props, Popover.Popup.State, Popover.Portal.Props, Popover.Portal.State, Popover.Positioner.Props, Popover.Positioner.State, Popover.Root.Actions, Popover.Root.ChangeEventDetails, Popover.Root.ChangeEventReason, Popover.Root.Props, Popover.Root.State, Popover.Title.Props, Popover.Title.State, Popover.Trigger.Props, Popover.Trigger.State, Popover.Viewport.Props, Popover.Viewport.State

Read more

Preview Card

A link that shows a destination preview without interrupting keyboard or screen reader navigation.

Outline

  • Keywords: React Preview Card, Preview Card Component, Link Hover Preview, Hover Card React, Hover Card, Link Tooltip, URL Preview, Link Preview Popup, Content Preview, Accessible Preview Popup, Detached Trigger Preview Card, Multiple Preview Card Triggers, Animated Preview Card, Headless React Components, Link Preview UI, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Detached triggers
      • Multiple triggers
      • Controlled mode with multiple triggers
      • Animating the Preview Card
        • Position and Size
        • Content
    • API reference
      • Root
      • Trigger
      • Portal
      • Backdrop
      • Positioner
      • Popup
      • Viewport
      • Arrow
    • createHandle
      • Handle
  • Exports:
    • Preview Card - Root
      • Props: actionsRef, children, defaultOpen, defaultTriggerId, handle, onOpenChange, onOpenChangeComplete, open, triggerId
    • Preview Card - Trigger
      • Props: className, closeDelay, delay, handle, payload, render, style
      • Data Attributes: data-popup-open
    • Preview Card - Portal
      • Props: className, container, keepMounted, render, style
    • Preview Card - Backdrop
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Preview Card - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --positioner-height, --positioner-width, --transform-origin
    • Preview Card - Popup
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-ending-style, data-open, data-side, data-starting-style
    • Preview Card - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-open, data-side, data-uncentered
    • Preview Card - Viewport
      • Props: children, className, render, style
      • Data Attributes: data-activation-direction, data-current, data-instant, data-previous, data-transitioning
      • CSS Variables: --popup-height, --popup-width
    • Preview Card - createHandle
    • Preview Card - Handle
  • Types: PreviewCard.Arrow.Props, PreviewCard.Arrow.State, PreviewCard.Backdrop.Props, PreviewCard.Backdrop.State, PreviewCard.Popup.Props, PreviewCard.Popup.State, PreviewCard.Portal.Props, PreviewCard.Portal.State, PreviewCard.Positioner.Props, PreviewCard.Positioner.State, PreviewCard.Root.Actions, PreviewCard.Root.ChangeEventDetails, PreviewCard.Root.ChangeEventReason, PreviewCard.Root.Props, PreviewCard.Root.State, PreviewCard.Trigger.Props, PreviewCard.Trigger.State, PreviewCard.Viewport.Props, PreviewCard.Viewport.State

Read more

Progress

Displays the status of a task that takes a long time.

Outline

  • Keywords: React Progress Bar, Progress Component, Progress Indicator, Loader, Loading Bar, Upload Progress, Download Progress, Task Status Indicator, Determinate Progress, Indeterminate Progress, Accessible Progress, Headless React Components, Loading Indicator, Base UI
  • Sections:
    • Anatomy
    • API reference
      • Root
      • Track
      • Indicator
      • Value
      • Label
  • Exports:
    • Progress - Root
      • Props: aria-valuetext, className, format, getAriaValueText, locale, max, min, render, style, value
      • Data Attributes: data-complete, data-indeterminate, data-progressing
    • Progress - Value
      • Props: children, className, render, style
      • Data Attributes: data-complete, data-indeterminate, data-progressing
    • Progress - Indicator
      • Props: className, render, style
      • Data Attributes: data-complete, data-indeterminate, data-progressing
    • Progress - Track
      • Props: className, render, style
      • Data Attributes: data-complete, data-indeterminate, data-progressing
    • Progress - Label
      • Props: className, render, style
      • Data Attributes: data-complete, data-indeterminate, data-progressing
  • Types: Progress.Indicator.Props, Progress.Indicator.State, Progress.Label.Props, Progress.Label.State, Progress.Root.Props, Progress.Root.State, Progress.Track.Props, Progress.Track.State, Progress.Value.Props, Progress.Value.State

Read more

Radio Group

Provides shared state to a series of radio buttons.

Outline

  • Keywords: React Radio Group, Radio Group Component, Grouped Radio Buttons, React Radio Button, Radio Button, Radio Input, Single Choice, Exclusive Choice, Mutually Exclusive, Option Selector, Option Button, Form Radio Control, Accessible Radio Group, Customizable Radio, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Labeling a radio group
      • Rendering as a native button
      • Form integration
    • API reference
      • RadioGroup
      • Root
      • Indicator
  • Exports:
    • Radio Group - Root
      • Props: className, disabled, inputRef, nativeButton, readOnly, render, required, style, value
      • Data Attributes: data-checked, data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-touched, data-unchecked, data-valid
    • Radio Group - Indicator
      • Props: className, keepMounted, render, style
      • Data Attributes: data-checked, data-dirty, data-disabled, data-ending-style, data-filled, data-focused, data-invalid, data-readonly, data-required, data-starting-style, data-touched, data-unchecked, data-valid
    • RadioGroup
      • Props: className, defaultValue, disabled, form, inputRef, name, onValueChange, readOnly, render, required, style, value
      • Data Attributes: data-disabled
  • Types: Radio.Indicator.Props, Radio.Indicator.State, Radio.Root.Props, Radio.Root.State, RadioGroup.ChangeEventDetails, RadioGroup.ChangeEventReason, RadioGroup.Props, RadioGroup.State, RadioGroupDataAttributes

Read more

Scroll Area

A native scroll container with custom scrollbars.

Outline

  • Keywords: React Scroll Area, Custom Scrollbars, Custom Scroll, Scrollbar, Styled Scrollbar, Virtual Scroll, Scroll Area Component, Overflow Container, Scrollable Region, Scrollable Content, Overflow Scroll, Gradient Scroll Fade, Scrollable Container, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Both scrollbars
      • Gradient scroll fade
      • Combining with Tabs
    • API reference
      • Root
      • Viewport
      • Content
      • Scrollbar
      • Thumb
      • Corner
  • Exports:
    • Scroll Area - Root
      • Props: className, overflowEdgeThreshold, render, style
      • Data Attributes: data-has-overflow-x, data-has-overflow-y, data-overflow-x-end, data-overflow-x-start, data-overflow-y-end, data-overflow-y-start, data-scrolling
      • CSS Variables: --scroll-area-corner-height, --scroll-area-corner-width
    • Scroll Area - Content
      • Props: className, render, style
      • Data Attributes: data-has-overflow-x, data-has-overflow-y, data-overflow-x-end, data-overflow-x-start, data-overflow-y-end, data-overflow-y-start, data-scrolling
    • Scroll Area - Viewport
      • Props: className, render, style
      • Data Attributes: data-has-overflow-x, data-has-overflow-y, data-overflow-x-end, data-overflow-x-start, data-overflow-y-end, data-overflow-y-start, data-scrolling
      • CSS Variables: --scroll-area-overflow-x-end, --scroll-area-overflow-x-start, --scroll-area-overflow-y-end, --scroll-area-overflow-y-start
    • Scroll Area - Thumb
      • Props: className, render, style
      • Data Attributes: data-orientation, data-scrolling
    • Scroll Area - Scrollbar
      • Props: className, keepMounted, orientation, render, style
      • Data Attributes: data-has-overflow-x, data-has-overflow-y, data-hovering, data-orientation, data-overflow-x-end, data-overflow-x-start, data-overflow-y-end, data-overflow-y-start, data-scrolling
      • CSS Variables: --scroll-area-thumb-height, --scroll-area-thumb-width
    • Scroll Area - Corner
      • Props: className, render, style
  • Types: ScrollArea.Content.Props, ScrollArea.Content.State, ScrollArea.Corner.Props, ScrollArea.Corner.State, ScrollArea.Root.Props, ScrollArea.Root.State, ScrollArea.Scrollbar.Props, ScrollArea.Scrollbar.State, ScrollArea.Thumb.Props, ScrollArea.Thumb.State, ScrollArea.Viewport.Props, ScrollArea.Viewport.State

Read more

Select

A common form component for choosing a predefined value in a dropdown menu.

Outline

  • Keywords: React Select Component, Dropdown Select, Select Box, Select Menu, Picker, Listbox, Choice Selector, Option List, Dropdown Menu, Combo Box, Multi Select React, Multiselect, Object Value Select, Single Select, Keyboard Navigation Select, Listbox Role, Accessible Select, Align Item with Trigger, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Positioning
    • Examples
      • Typed wrapper component
      • Formatting the value
      • Labeling a select
      • Placeholder values
      • Multiple selection
      • Object values
      • Grouped
    • API reference
      • Root
      • Label
      • Trigger
      • Value
      • Icon
      • Backdrop
      • Portal
      • Positioner
      • Popup
      • List
      • Arrow
      • Item
      • ItemText
      • ItemIndicator
      • Group
      • GroupLabel
      • ScrollUpArrow
      • ScrollDownArrow
      • Separator
  • Exports:
    • Select - Root
      • Props: actionsRef, autoComplete, children, defaultOpen, defaultValue, disabled, form, highlightItemOnHover, id, inputRef, isItemEqualToValue, itemToStringLabel, itemToStringValue, items, modal, multiple, name, onOpenChange, onOpenChangeComplete, onValueChange, open, readOnly, required, value
    • Select - Trigger
      • Props: children, className, disabled, nativeButton, render, style
      • Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-placeholder, data-popup-open, data-popup-side, data-pressed, data-readonly, data-required, data-touched, data-valid
    • Select - Value
      • Props: children, className, placeholder, render, style
      • Data Attributes: data-placeholder
    • Select - Icon
      • Props: className, render, style
      • Data Attributes: data-popup-open
    • Select - List
      • Props: className, render, style
    • Select - Portal
      • Props: className, container, render, style
    • Select - Backdrop
      • Props: className, render, style
      • Data Attributes: data-closed, data-ending-style, data-open, data-starting-style
    • Select - Positioner
      • Props: align, alignItemWithTrigger, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --transform-origin
    • Select - Popup
      • Props: children, className, finalFocus, render, style
      • Data Attributes: data-align, data-closed, data-ending-style, data-open, data-side, data-starting-style
    • Select - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-open, data-side, data-uncentered
    • Select - Item
      • Props: children, className, disabled, label, nativeButton, render, style, value
      • Data Attributes: data-disabled, data-highlighted, data-selected
    • Select - Group
      • Props: className, render, style
    • Select - GroupLabel
      • Props: className, render, style
    • Select - Separator
      • Props: className, orientation, render, style
      • Data Attributes: data-orientation
    • Select - Label
      • Props: className, render, style
    • Select - ItemText
      • Props: className, render, style
    • Select - ItemIndicator
      • Props: children, className, keepMounted, render, style
      • Data Attributes: data-ending-style, data-starting-style
    • Select - ScrollUpArrow
      • Props: className, keepMounted, render, style
      • Data Attributes: data-direction, data-ending-style, data-side, data-starting-style, data-visible
    • Select - ScrollDownArrow
      • Props: className, keepMounted, render, style
      • Data Attributes: data-direction, data-ending-style, data-side, data-starting-style, data-visible
  • Types: Select.Arrow.Props, Select.Arrow.State, Select.Backdrop.Props, Select.Backdrop.State, Select.Group.Props, Select.Group.State, Select.GroupLabel.Props, Select.GroupLabel.State, Select.Icon.Props, Select.Icon.State, Select.Item.Props, Select.Item.State, Select.ItemIndicator.Props, Select.ItemIndicator.State, Select.ItemText.Props, Select.ItemText.State, Select.Label.Props, Select.Label.State, Select.List.Props, Select.List.State, Select.Popup.Props, Select.Popup.State, Select.Portal.Props, Select.Portal.State, Select.Positioner.Props, Select.Positioner.State, Select.Root.Actions, Select.Root.ChangeEventDetails, Select.Root.ChangeEventReason, Select.Root.OpenChangeEventDetails, Select.Root.Props, Select.Root.State, Select.ScrollDownArrow.Props, Select.ScrollDownArrow.State, Select.ScrollUpArrow.Props, Select.ScrollUpArrow.State, Select.Separator.Props, Select.Separator.State, Select.Trigger.Props, Select.Trigger.State, Select.Value.Props, Select.Value.State

Read more

Separator

A separator element accessible to screen readers.

Outline

  • Keywords: React Separator, Divider Component, Divider, Horizontal Rule, Horizontal Divider, Vertical Divider, Visual Separator, Section Divider, HR, Accessible Separator, Screen Reader Separator, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • API reference
  • Exports:
    • Separator
      • Props: className, orientation, render, style
      • Data Attributes: data-orientation
  • Types: Separator.Props, Separator.State, SeparatorDataAttributes

Read more

Slider

An easily stylable range input.

Outline

  • Keywords: React Slider, Range Slider Component, Range Input, Range Control, Track Control, Value Selector, Keyboard Slider Control, Dual Slider, Double Slider, Two-Handle Slider, Multi Thumb Slider, Thumb Alignment Edge, Accessible Slider, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Labeling a slider
      • Range slider
      • Steps
      • Marks
      • Thumb alignment
      • Vertical
      • Form integration
    • API reference
      • Root
      • Label
      • Value
      • Control
      • Track
      • Indicator
      • Thumb
  • Exports:
    • Slider - Root
      • Props: className, defaultValue, disabled, form, format, largeStep, locale, max, min, minStepsBetweenValues, name, onValueChange, onValueCommitted, orientation, render, step, style, thumbAlignment, thumbCollisionBehavior, value
      • Data Attributes: data-dirty, data-disabled, data-dragging, data-focused, data-invalid, data-orientation, data-touched, data-valid
    • Slider - Value
      • Props: children, className, render, style
      • Data Attributes: data-dirty, data-disabled, data-dragging, data-focused, data-invalid, data-orientation, data-touched, data-valid
    • Slider - Indicator
      • Props: className, render, style
      • Data Attributes: data-dirty, data-disabled, data-dragging, data-focused, data-invalid, data-orientation, data-touched, data-valid
    • Slider - Track
      • Props: className, render, style
      • Data Attributes: data-dirty, data-disabled, data-dragging, data-focused, data-invalid, data-orientation, data-touched, data-valid
    • Slider - Thumb
      • Props: aria-valuetext, className, disabled, getAriaLabel, getAriaValueText, index, inputRef, onBlur, onFocus, onKeyDown, render, style, tabIndex
      • Data Attributes: data-dirty, data-disabled, data-dragging, data-focused, data-index, data-invalid, data-orientation, data-touched, data-valid
    • Slider - Control
      • Props: className, render, style
      • Data Attributes: data-dirty, data-disabled, data-dragging, data-focused, data-invalid, data-orientation, data-touched, data-valid
    • Slider - Label
      • Props: className, render, style
  • Types: Slider.Control.Props, Slider.Control.State, Slider.Indicator.Props, Slider.Indicator.State, Slider.Label.Props, Slider.Label.State, Slider.Root.ChangeEventDetails, Slider.Root.ChangeEventReason, Slider.Root.CommitEventDetails, Slider.Root.CommitEventReason, Slider.Root.Props, Slider.Root.State, Slider.Thumb.Props, Slider.Thumb.State, Slider.Track.Props, Slider.Track.State, Slider.Value.Props, Slider.Value.State

Read more

Switch

A control that indicates whether a setting is on or off.

Outline

  • Keywords: React Switch, Toggle Switch Component, Toggle Switch, Toggle Button, On/Off Control, On Off Switch, Binary Switch, Checkbox Alternative, Form Toggle Control, Aria Switch Role, Accessible Switch, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Labeling a switch
      • Rendering as a native button
      • Form integration
    • API reference
      • Root
      • Thumb
  • Exports:
    • Switch - Root
      • Props: checked, className, defaultChecked, disabled, form, id, inputRef, name, nativeButton, onCheckedChange, readOnly, render, required, style, uncheckedValue, value
      • Data Attributes: data-checked, data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-touched, data-unchecked, data-valid
    • Switch - Thumb
      • Props: className, render, style
      • Data Attributes: data-checked, data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-touched, data-unchecked, data-valid
  • Types: Switch.Root.ChangeEventDetails, Switch.Root.ChangeEventReason, Switch.Root.Props, Switch.Root.State, Switch.Thumb.Props, Switch.Thumb.State

Read more

Tabs

A component for toggling between related panels on the same page.

Outline

  • Keywords: React Tabs, Tabbed Interface Component, Tab Panel, Tab Control, Tabbed Navigation, Tabbed UI, Page Switcher, Content Switcher, View Switcher, Tab List Indicator, Tablist, Tabpanel, Keyboard Navigation Tabs, Controlled Tabs, Accessible Tabs, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Animated panels
      • Links
    • API reference
      • Root
      • List
      • Tab
      • Indicator
      • Panel
  • Exports:
    • Tabs - Root
      • Props: className, defaultValue, onValueChange, orientation, render, style, value
      • Data Attributes: data-activation-direction, data-orientation
    • Tabs - List
      • Props: activateOnFocus, className, loopFocus, render, style
      • Data Attributes: data-activation-direction, data-orientation
    • Tabs - Panel
      • Props: className, keepMounted, render, style, value
      • Data Attributes: data-activation-direction, data-ending-style, data-hidden, data-index, data-orientation, data-starting-style
    • Tabs - Indicator
      • Props: className, render, renderBeforeHydration, style
      • Data Attributes: data-activation-direction, data-orientation
      • CSS Variables: --active-tab-bottom, --active-tab-height, --active-tab-left, --active-tab-right, --active-tab-top, --active-tab-width
    • Tabs - Tab
      • Props: className, disabled, nativeButton, render, style, value
      • Data Attributes: data-activation-direction, data-active, data-disabled, data-orientation
  • Types: Tabs.Indicator.Props, Tabs.Indicator.State, Tabs.List.Props, Tabs.List.State, Tabs.Panel.Metadata, Tabs.Panel.Props, Tabs.Panel.State, Tabs.Root.ChangeEventDetails, Tabs.Root.ChangeEventReason, Tabs.Root.Orientation, Tabs.Root.Props, Tabs.Root.State, Tabs.Tab.ActivationDirection, Tabs.Tab.Metadata, Tabs.Tab.Position, Tabs.Tab.Props, Tabs.Tab.Size, Tabs.Tab.State, Tabs.Tab.Value

Read more

Toast

Generates toast notifications.

Outline

  • Keywords: React Toast, Toast Notification, Toast Notifications, Notification Component, Notification, Snackbar, Message Notification, Alert Notification, Alert Message, Flash Message, Push Notification, Temporary Message, Dismissible Notification, Toast Message, Toast Manager, Anchored Toast, Swipe Dismiss Toast, Status Message, Timed Notification, Stacked Toasts, Live Region, Accessible Toast, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • General usage
    • Global manager
    • Stacking and animations
    • Examples
      • Anchored toasts
      • Custom position
      • Undo action
      • Promise
      • Custom
      • Deduplicated toast
      • Varying heights
    • API reference
      • Provider
      • Portal
      • Viewport
      • Root
      • Content
      • Title
      • Description
      • Action
      • Close
      • Positioner
      • Arrow
    • useToastManager
      • add method
      • update method
      • close method
      • promise method
    • Additional types
  • Exports:
    • Toast - Root
      • Props: className, render, style, swipeDirection, toast
      • Data Attributes: data-ending-style, data-expanded, data-limited, data-starting-style, data-swipe-direction, data-swiping, data-type
      • CSS Variables: --toast-height, --toast-index, --toast-offset-y, --toast-swipe-movement-x, --toast-swipe-movement-y
    • Toast - Provider
      • Props: children, limit, timeout, toastManager
    • Toast - Portal
      • Props: className, container, render, style
    • Toast - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style, toast
      • Data Attributes: data-align, data-anchor-hidden, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --transform-origin
    • Toast - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-side, data-uncentered
    • Toast - Content
      • Props: className, render, style
      • Data Attributes: data-behind, data-expanded
    • Toast - Title
      • Props: className, render, style
      • Data Attributes: data-type
    • Toast - Description
      • Props: className, render, style
      • Data Attributes: data-type
    • Toast - Close
      • Props: className, nativeButton, render, style
      • Data Attributes: data-type
    • Toast - Action
      • Props: className, nativeButton, render, style
      • Data Attributes: data-type
    • Toast - Viewport
      • Props: className, render, style
      • Data Attributes: data-expanded
      • CSS Variables: --toast-frontmost-height
    • Toast - createToastManager
    • Toast - useToastManager
  • Types: Toast.Action.Props, Toast.Action.State, Toast.Arrow.Props, Toast.Arrow.State, Toast.Close.Props, Toast.Close.State, Toast.Content.Props, Toast.Content.State, Toast.Description.Props, Toast.Description.State, Toast.Portal.Props, Toast.Portal.State, Toast.Positioner.Props, Toast.Positioner.State, Toast.Provider.Props, Toast.Provider.State, Toast.Root.Props, Toast.Root.State, Toast.Root.ToastObject, Toast.Title.Props, Toast.Title.State, Toast.Viewport.Props, Toast.Viewport.State

Read more

Toggle

A two-state button that can be on or off.

Outline

  • Keywords: React Toggle, Toggle Button Component, Two State Button, Press Button, Push Toggle, Pressed State Button, Toggle Control, ARIA Pressed Control, Accessible Toggle, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • API reference
  • Exports:
    • Toggle
      • Props: className, defaultPressed, disabled, nativeButton, onPressedChange, pressed, render, style, value
      • Data Attributes: data-disabled, data-pressed
  • Types: Toggle.ChangeEventDetails, Toggle.ChangeEventReason, Toggle.Props, Toggle.State, ToggleDataAttributes

Read more

Toggle Group

Provides a shared state to a series of toggle buttons.

Outline

  • Keywords: React Toggle Group, Toggle Button Group, Segmented Control, Button Set, Radio Group Alternative, Exclusive Selection Toggle, Multi Select Toggle Buttons, Accessible Toggle Group, Headless React Components, Base UI
  • Sections:
    • Anatomy
    • Examples
      • Multiple
    • API reference
  • Exports:
    • ToggleGroup
      • Props: className, defaultValue, disabled, loopFocus, multiple, onValueChange, orientation, render, style, value
      • Data Attributes: data-disabled, data-multiple, data-orientation
  • Types: ToggleGroup.ChangeEventDetails, ToggleGroup.ChangeEventReason, ToggleGroup.Props, ToggleGroup.State, ToggleGroupDataAttributes

Read more

Toolbar

A container for grouping a set of buttons and controls.

Outline

  • Keywords: React Toolbar, Toolbar Button Group, Action Bar, Button Bar, Command Strip, Headless Toolbar Component, Accessible Toolbar, Popup Trigger Toolbar, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Examples
      • Using with Menu
      • Using with Tooltip
      • Using with NumberField
    • API reference
      • Root
      • Button
      • Link
      • Input
      • Group
      • Separator
  • Exports:
    • Toolbar - Root
      • Props: className, disabled, loopFocus, orientation, render, style
      • Data Attributes: data-disabled, data-orientation
    • Toolbar - Input
      • Props: className, defaultValue, disabled, focusableWhenDisabled, render, style
      • Data Attributes: data-disabled, data-focusable, data-orientation
    • Toolbar - Group
      • Props: className, disabled, render, style
      • Data Attributes: data-disabled, data-orientation
    • Toolbar - Separator
      • Props: className, orientation, render, style
      • Data Attributes: data-orientation
    • Toolbar - Button
      • Props: className, disabled, focusableWhenDisabled, nativeButton, render, style
      • Data Attributes: data-disabled, data-focusable, data-orientation
    • Toolbar - Link
      • Props: className, render, style
      • Data Attributes: data-orientation
  • Types: Toolbar.Button.Props, Toolbar.Button.State, Toolbar.Group.Props, Toolbar.Group.State, Toolbar.Input.Props, Toolbar.Input.State, Toolbar.Link.Props, Toolbar.Link.State, Toolbar.Root.ItemMetadata, Toolbar.Root.Orientation, Toolbar.Root.Props, Toolbar.Root.State, Toolbar.Separator.Props, Toolbar.Separator.State

Read more

Tooltip

A popup that appears when an element is hovered or focused, showing a hint for sighted users.

Outline

  • Keywords: React Tooltip, Tooltip Component, Detached Trigger Tooltip, Hint, Help Text, Hover Text, Hover Hint, Info Popup, Infotip, Aria Describedby Tooltip, Accessible Tooltip, Multiple Tooltip Triggers, Animated Tooltip, Headless React Components, Base UI
  • Sections:
    • Usage guidelines
    • Anatomy
    • Alternatives to tooltips
      • Infotips
      • Description text
      • Contextual feedback messages
    • Examples
      • Detached triggers
      • Multiple triggers
      • Controlled mode with multiple triggers
      • Animating the Tooltip
        • Position and Size
        • Content
    • API reference
      • Provider
      • Root
      • Trigger
      • Portal
      • Positioner
      • Popup
      • Arrow
      • Viewport
    • createHandle
      • Handle
  • Exports:
    • Tooltip - Root
      • Props: actionsRef, children, defaultOpen, defaultTriggerId, disableHoverablePopup, disabled, handle, onOpenChange, onOpenChangeComplete, open, trackCursorAxis, triggerId
    • Tooltip - Provider
      • Props: children, closeDelay, delay, timeout
    • Tooltip - Trigger
      • Props: className, closeDelay, closeOnClick, delay, disabled, handle, payload, render, style
      • Data Attributes: data-popup-open, data-trigger-disabled
    • Tooltip - Portal
      • Props: className, container, keepMounted, render, style
    • Tooltip - Positioner
      • Props: align, alignOffset, anchor, arrowPadding, className, collisionAvoidance, collisionBoundary, collisionPadding, disableAnchorTracking, positionMethod, render, side, sideOffset, sticky, style
      • Data Attributes: data-align, data-anchor-hidden, data-closed, data-open, data-side
      • CSS Variables: --anchor-height, --anchor-width, --available-height, --available-width, --positioner-height, --positioner-width, --transform-origin
    • Tooltip - Popup
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-ending-style, data-instant, data-open, data-side, data-starting-style
    • Tooltip - Arrow
      • Props: className, render, style
      • Data Attributes: data-align, data-closed, data-instant, data-open, data-side, data-uncentered
    • Tooltip - Viewport
      • Props: children, className, render, style
      • Data Attributes: data-activation-direction, data-current, data-instant, data-previous, data-transitioning
      • CSS Variables: --popup-height, --popup-width
    • Tooltip - createHandle
    • Tooltip - Handle
  • Types: Tooltip.Arrow.Props, Tooltip.Arrow.State, Tooltip.Popup.Props, Tooltip.Popup.State, Tooltip.Portal.Props, Tooltip.Portal.State, Tooltip.Positioner.Props, Tooltip.Positioner.State, Tooltip.Provider.Props, Tooltip.Provider.State, Tooltip.Root.Actions, Tooltip.Root.ChangeEventDetails, Tooltip.Root.ChangeEventReason, Tooltip.Root.Props, Tooltip.Root.State, Tooltip.Trigger.Props, Tooltip.Trigger.State, Tooltip.Viewport.Props, Tooltip.Viewport.State

Read more

export const metadata =
/** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */ ({
robots: {
index: false,
},
other: {
audience: 'private',
},
});

Src App (Docs) React Handbook Page (`docs/src/app/(docs)/react/handbook/page.mdx`)

Handbook

Styling

A guide to styling Base UI components with your preferred styling engine.

Outline

  • Keywords: Base UI Styling, Tailwind Base UI, CSS Modules Base UI, CSS-in-JS Base UI, Style Hooks Data Attributes, Unstyled React Components, Handbook Styling, Headless UI Styling, Theming, Custom Styles, Utility First CSS, Headless Components Styling
  • Sections:
    • Style hooks
      • CSS classes
      • Data attributes
      • CSS variables
      • Style prop
    • Tailwind CSS
    • CSS Modules
    • CSS-in-JS

Read more

Animation

A guide to animating Base UI components.

Outline

  • Keywords: Base UI Animation, React Component Animations, CSS Transition Guide, Motion Framer Integration, Animation Data Attributes, Handbook Animation, Spring Animations, Enter Exit Animations, Transition Hooks, Animated Components, Keyframe Animations
  • Sections:
    • CSS transitions
    • CSS animations
    • JavaScript animations
      • Animating components unmounted from DOM when closed with Motion
      • Animating components kept in DOM when closed with Motion
      • Animating Select component with Motion
      • Manual unmounting

Read more

Composition

A guide to composing Base UI components with your own React components.

Outline

  • Keywords: Base UI Composition, React Render Prop, Compose Headless Components, Custom Trigger Render, Nested Render Props, Composition Handbook, Component Composition, Render Props Pattern, Compound Components, Polymorphic Components, As Prop, Custom Elements, Wrapper Components
  • Sections:
    • Composing custom React components
    • Composing multiple components
    • Changing the default rendered element
    • Render function

Read more

Customization

A guide to customizing the behavior of Base UI components.

Outline

  • Keywords: Base UI Customization, React eventDetails, Control Base UI State, Cancel Base UI Events, Allow Propagation Tooltip, Customization Handbook, Event Handlers, Controlled Components, Uncontrolled Components, Component Behavior, Event Callbacks, State Management, Component Props, Override Behavior
  • Sections:
    • Base UI events
      • Canceling a Base UI event
      • Allowing propagation of the DOM event
    • Preventing Base UI from handling a React event
    • Controlling components with state

Read more

Forms

A guide to building forms with Base UI components.

Outline

  • Keywords: Base UI Forms, React Accessible Forms, Field Validation Handbook, React Hook Form Integration, TanStack Form Guide, Constraint Validation API, Handbook Forms, Form State, Form Library, Form Handling, Input Validation, Error Messages, Form Submission, Accessible Forms, ARIA Forms
  • Sections:
    • Naming form controls
      • Input controls
      • Trigger-based controls
      • Fallback
      • Describing the control
      • Labeling control groups
    • Building form fields
    • Submitting data
    • Constraint validation
    • Custom validation
    • Server-side validation
    • Displaying errors
    • React Hook Form
      • Initialize the form
      • Integrate components
      • Field validation
      • Submitting data
    • TanStack Form
      • Initialize the form
      • Integrate components
      • Form validation
      • Field validation
      • Submitting data

Read more

TypeScript

A guide to using TypeScript with Base UI.

Outline

  • Keywords: Base UI TypeScript, Component Props Namespace, Combobox ChangeEventDetails, Popover Positioner State, Toast Actions Ref Types, Use Render Component Props, Handbook TypeScript, Type Definitions, Type Safety, Generics, Component Types, Props Types, Event Types, Ref Types, Type Inference, Strongly Typed Components
  • Sections:
    • Namespaces
      • Props
      • State
      • Events
      • Other accessible types

Read more

export const metadata =
/** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */ ({
robots: {
index: false,
},
other: {
audience: 'private',
},
});

Src App (Docs) React Overview Page (`docs/src/app/(docs)/react/overview/page.mdx`)

Overview

Quick start

A quick guide to getting started with Base UI.

Outline

  • Keywords: Base UI Quick Start, Install Base UI, Base UI shadcn, Base UI shadcn/ui, React Portal Setup, iOS Safari Backdrop Fix, Popover Assembly Example, llms.txt Link, Getting Started Guide, npm Install, Setup Guide, Installation Guide, Getting Started Tutorial, First Steps, Beginner Guide
  • Sections:
    • Install the library
    • Set up
      • Portals
      • iOS 26+ Safari
    • Assemble a component
    • Pre-styled components
    • Working with LLMs
    • Next steps

Read more

Accessibility

Learn how to make the most of Base UI's accessibility features and guidelines.

Outline

  • Keywords: Base UI Accessibility, React Accessibility Guidelines, Keyboard Navigation Base UI, Focus Management Tips, Color Contrast Guidance, Accessible Labels Base UI, Accessibility Overview, WCAG Compliance, ARIA Attributes, A11y, Screen Reader Support, Accessible UI, Inclusive Design
  • Sections:
    • Keyboard navigation
    • Focus management
    • Color contrast
    • Accessible labels
    • Testing

Read more

Releases

Changelogs for each Base UI release.

Outline

  • Keywords: Base UI releases, Base UI changelog, Release notes beta, Breaking changes Base UI, Component updates history, Headless React release log, Version history, Changelog history, Upgrade guide, Migration guide, What's new, Release updates
  • Sections:
    • Canary releases
    • Full release notes

Read more

Community

The Base UI ecosystem, support channels, and ways to stay up to date.

Outline

  • Keywords: Base UI Community, Base UI shadcn, Base UI shadcn/ui, Base UI GitHub, Base UI Discord, Base UI X, Base UI Bluesky, Base UI Styling, Base UI Ecosystem, Base UI Support, Headless React Community, Accessible React Components
  • Sections:
    • shadcn/ui
    • Styled libraries
    • Unofficial ports
    • Get help and contribute
      • GitHub
      • Discord
    • Stay up to date
      • X
      • Bluesky
      • GitHub releases

Read more

About Base UI

An open-source React component library for building accessible user interfaces.

Outline

  • Keywords: About Base UI, Base UI Team, Headless React Components, Accessible React Library, Open Source UI Components, Base UI Community, Base UI Overview, Unstyled Components, Component Library, Headless UI Library, React UI Toolkit, MUI Team, Radix Alternative
  • Sections:
    • Features
      • Headless
      • Accessible
      • Composable
    • Team
    • Browser support
    • React versions
    • Bundler support
    • Community

Read more

export const metadata =
/** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */ ({
robots: {
index: false,
},
other: {
audience: 'private',
},
});

Src App (Docs) React Utils Page (`docs/src/app/(docs)/react/utils/page.mdx`)

Utils

CSP Provider

Configures CSP-related behavior for inline tags rendered by Base UI components.

Outline

  • Keywords: Base UI CSP Provider, Content Security Policy, CSP nonce, React CSP, Inline script nonce, Inline style nonce
  • Sections:
    • Anatomy
    • Supplying a nonce
    • Disable inline style elements
    • Inline style attributes
    • API reference
  • Exports:
    • CSPProvider
      • Props: children, disableStyleElements, nonce
  • Types: CSPProvider.Props, CSPProvider.State

Read more

Direction Provider

Enables RTL behavior for Base UI components.

Outline

  • Keywords: Base UI Direction Provider, React RTL Context, Text Direction Hook, useDirection Base UI, Headless RTL Components, Internationalization, i18n, Bidirectional Text, Locale Support, Arabic Hebrew Support, LTR RTL Switch
  • Sections:
    • Anatomy
    • API reference
      • DirectionProvider
      • useDirection
  • Exports:
    • DirectionProvider
      • Props: children, direction
    • useDirection
  • Types: DirectionProvider.Props, DirectionProvider.State, TextDirection

Read more

mergeProps

A utility to merge multiple sets of React props.

Outline

  • Sections:
    • How merging works
      • Preventing Base UI's default behavior
    • Passing a function instead of an object
    • API reference
      • mergeProps
      • mergePropsN
  • Exports:
    • makeEventPreventable
      • Parameters: event
    • mergeClassNames
      • Parameters: ourClassName, theirClassName
    • mergeProps
      • Parameters: a, b, c, d, e
    • mergePropsN
      • Parameters: props

Read more

useRender

Hook for enabling a render prop in custom components.

Outline

  • Keywords: Base UI useRender, React Render Prop Hook, Merge Props Helper, Merge Refs Hook, Radix asChild Migration, Component Composition, Props Spreading, Ref Forwarding, Custom Components, asChild Pattern, Slot Pattern
  • Sections:
    • Examples
    • Merging props
    • Merging refs
    • TypeScript
    • Migrating from Radix UI
    • Render prop and polymorphism
    • API reference
  • Exports:
    • ComponentRenderFn
    • useRender
      • Parameters: params
  • Types: HTMLProps, UseRenderComponentProps, UseRenderElementProps, UseRenderParameters, UseRenderRenderProp, UseRenderReturnValue, UseRenderState, useRender.ComponentProps, useRender.ElementProps, useRender.Parameters, useRender.RenderProp, useRender.ReturnValue, useRender.State

Read more

export const metadata =
/** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */ ({
robots: {
index: false,
},
other: {
audience: 'private',
},
});

Src App (Docs) React Components Accordion Page (`docs/src/app/(docs)/react/components/accordion/page.mdx`)

Accordion

A set of collapsible panels with headings.

import { DemoAccordionHero } from './demos/hero';

Anatomy

Import the component and assemble its parts:

jsx title="anatomy"
import { Accordion } from '@base-ui/react/accordion';

<Accordion.Root>
  <Accordion.Item>
    <Accordion.Header>
      <Accordion.Trigger />
    </Accordion.Header>
    <Accordion.Panel />
  </Accordion.Item>
</Accordion.Root>;

Examples

Open multiple panels

You can set up the accordion to allow multiple panels to be open at the same time using the multiple prop.

import { DemoAccordionMultiple } from './demos/multiple';

Hidden until found

The hiddenUntilFound prop hides closed panels with hidden="until-found" so the browser can search their contents and reveal the matching panel automatically. It can be set on each Accordion.Panel, or once on Accordion.Root to apply to all panels.

To try it, press Ctrl+F (Cmd+F on macOS) and search for "restocking"—the browser opens the closed panel containing the match. When hiddenUntilFound is enabled, closed panels always remain mounted in the DOM, which also makes their contents indexable by search engines.

Older browsers that don't support hidden="until-found" keep panels hidden until their trigger opens them, and find-in-page skips over the contents.

import { DemoAccordionHiddenUntilFound } from './demos/hidden-until-found';

API reference

import { TypesAccordion } from './types';

Root

<TypesAccordion.Root />

Item

<TypesAccordion.Item />

<TypesAccordion.Header />

Trigger

<TypesAccordion.Trigger />

Panel

<TypesAccordion.Panel />

export const metadata = {
keywords: [
'React Accordion',
'Accordion Component',
'Collapsible Content',
'Expandable Panel',
'Accessible Accordion',
'Multi-Panel UI',
'Disclosure Widget',
'FAQ Component',
'Headless React Components',
'Base UI',
],
};

Src App (Docs) React Components Accordion Types (`docs/src/app/(docs)/react/components/accordion/types.md`)

Accordion

API Reference

Root

Groups all parts of the accordion.
Renders a `` element.

Root Props:

Prop Type Default Description
defaultValue Value[] - The uncontrolled value of the item(s) that should be initially expanded. To render a controlled accordion, use the value prop instead.
value Value[] - The controlled value of the item(s) that should be expanded. To render an uncontrolled accordion, use the defaultValue prop instead.
onValueChange ((value: Value[], eventDetails: Accordion.Root.ChangeEventDetails) => void) - Event handler called when an accordion item is expanded or collapsed. Provides the new value as an argument.
hiddenUntilFound boolean false Allows the browser's built-in page search to find and expand the panel contents. Overrides the keepMounted prop and uses hidden="until-found" to hide the element without removing it from the DOM.
loopFocus boolean - Deprecated following the APG guidance update to remove roving focus. This prop no longer affects keyboard focus behavior.
multiple boolean false Whether multiple items can be open at the same time.
disabled boolean false Whether the component should ignore user interaction.
orientation Orientation 'vertical' Deprecated following the APG guidance update to remove roving focus. This prop no longer affects keyboard focus behavior.
className string | ((state: Accordion.Root.State<Value>) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Accordion.Root.State<Value>) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted boolean false Whether to keep the element in the DOM while the panel is closed. This prop is ignored when hiddenUntilFound is used.
render ReactElement | ((props: HTMLProps, state: Accordion.Root.State<Value>) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Root Data Attributes:

Attribute Type Description
data-orientation - Indicates the orientation of the accordion.
data-disabled - Present when the accordion is disabled.

Root.Props

Re-export of Root props.

Root.State

typescript
type AccordionRootState<TValue = any> = {
  /**
   * The current value.
   * Treat it as read-only: it may be a shared frozen array when no value is set.
   */
  value: TValue[];
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /**
   * The component orientation.
   *
   * Deprecated following the [APG guidance update](https://github.com/w3c/aria-practices/pull/3434)
   * to remove roving focus.
   *
   * This state no longer affects keyboard focus behavior.
   * @deprecated
   */
  orientation: Orientation;
};

Root.ChangeEventReason

typescript
type AccordionRootChangeEventReason = 'trigger-press' | 'none';

Root.ChangeEventDetails

typescript
type AccordionRootChangeEventDetails = (
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'none'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};

Root.Value

typescript
type AccordionRootValue<TValue = any> = TValue[];

Trigger

A button that opens and closes the corresponding panel.
Renders a `` element.

Trigger Props:

Prop Type Default Description
nativeButton boolean true Whether the component renders a native element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example,).
className string | ((state: Accordion.Trigger.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Accordion.Trigger.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Accordion.Trigger.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Trigger Data Attributes:

Attribute Type Description
data-panel-open - Present when the accordion panel is open.
data-disabled - Present when the accordion item is disabled.
data-index number Indicates the index of the accordion item.

Trigger.Props

Re-export of Trigger props.

Trigger.State

typescript
type AccordionTriggerState = {
  /** Whether the accordion item's panel is currently hidden. */
  hidden: boolean;
  /** The item index. */
  index: number;
  /** Whether the component is open. */
  open: boolean;
  /**
   * The current value.
   * Treat it as read-only: it may be a shared frozen array when no value is set.
   */
  value: any[];
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /**
   * The component orientation.
   *
   * Deprecated following the [APG guidance update](https://github.com/w3c/aria-practices/pull/3434)
   * to remove roving focus.
   *
   * This state no longer affects keyboard focus behavior.
   * @deprecated
   */
  orientation: Orientation;
};

Item

Groups an accordion header with the corresponding panel.
Renders a `` element.

Item Props:

Prop Type Default Description
value any - A unique value that identifies this accordion item. If no value is provided, a unique ID will be generated automatically. Use when controlling the accordion programmatically, or to set an initial open state.
onOpenChange ((open: boolean, eventDetails: Accordion.Item.ChangeEventDetails) => void) - Event handler called when the panel is opened or closed.
disabled boolean false Whether the component should ignore user interaction.
className string | ((state: Accordion.Item.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Accordion.Item.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Accordion.Item.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

value Prop Example:

tsx
<Accordion.Root value={['a']}>
  <Accordion.Item value="a" /> // initially open
  <Accordion.Item value="b" /> // initially closed
</Accordion.Root>

Item Data Attributes:

Attribute Type Description
data-open - Present when the accordion item is open.
data-disabled - Present when the accordion item is disabled.
data-index number Indicates the index of the accordion item.

Item.Props

Re-export of Item props.

Item.State

typescript
type AccordionItemState = {
  /** Whether the accordion item's panel is currently hidden. */
  hidden: boolean;
  /** The item index. */
  index: number;
  /** Whether the component is open. */
  open: boolean;
  /**
   * The current value.
   * Treat it as read-only: it may be a shared frozen array when no value is set.
   */
  value: any[];
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /**
   * The component orientation.
   *
   * Deprecated following the [APG guidance update](https://github.com/w3c/aria-practices/pull/3434)
   * to remove roving focus.
   *
   * This state no longer affects keyboard focus behavior.
   * @deprecated
   */
  orientation: Orientation;
};

Item.ChangeEventReason

typescript
type AccordionItemChangeEventReason = 'trigger-press' | 'none';

Item.ChangeEventDetails

typescript
type AccordionItemChangeEventDetails = (
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'none'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};

A heading that labels the corresponding panel.
Renders an <h3> element.

Header Props:

Prop Type Default Description
className string | ((state: Accordion.Header.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Accordion.Header.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Accordion.Header.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Header Data Attributes:

Attribute Type Description
data-open - Present when the accordion item is open.
data-disabled - Present when the accordion item is disabled.
data-index number Indicates the index of the accordion item.

Header.Props

Re-export of Header props.

Header.State

typescript
type AccordionHeaderState = {
  /** Whether the accordion item's panel is currently hidden. */
  hidden: boolean;
  /** The item index. */
  index: number;
  /** Whether the component is open. */
  open: boolean;
  /**
   * The current value.
   * Treat it as read-only: it may be a shared frozen array when no value is set.
   */
  value: any[];
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /**
   * The component orientation.
   *
   * Deprecated following the [APG guidance update](https://github.com/w3c/aria-practices/pull/3434)
   * to remove roving focus.
   *
   * This state no longer affects keyboard focus behavior.
   * @deprecated
   */
  orientation: Orientation;
};

Panel

A collapsible panel with the accordion item contents.
Renders a `` element.

Panel Props:

Prop Type Default Description
hiddenUntilFound boolean false Allows the browser's built-in page search to find and expand the panel contents. Overrides the keepMounted prop and uses hidden="until-found" to hide the element without removing it from the DOM.
className string | ((state: Accordion.Panel.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Accordion.Panel.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted boolean false Whether to keep the element in the DOM while the panel is closed. This prop is ignored when hiddenUntilFound is used.
render ReactElement | ((props: HTMLProps, state: Accordion.Panel.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Panel Data Attributes:

Attribute Type Description
data-open - Present when the accordion panel is open.
data-orientation - Indicates the orientation of the accordion.
data-disabled - Present when the accordion item is disabled.
data-index number Indicates the index of the accordion item.
data-starting-style - Present when the panel begins animating in.
data-ending-style - Present when the panel is animating out.

Panel CSS Variables:

Variable Type Description
--accordion-panel-height number The accordion panel's height.
--accordion-panel-width number The accordion panel's width.

Panel.Props

Re-export of Panel props.

Panel.State

typescript
type AccordionPanelState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the accordion item's panel is currently hidden. */
  hidden: boolean;
  /** The item index. */
  index: number;
  /** Whether the component is open. */
  open: boolean;
  /**
   * The current value.
   * Treat it as read-only: it may be a shared frozen array when no value is set.
   */
  value: any[];
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /**
   * The component orientation.
   *
   * Deprecated following the [APG guidance update](https://github.com/w3c/aria-practices/pull/3434)
   * to remove roving focus.
   *
   * This state no longer affects keyboard focus behavior.
   * @deprecated
   */
  orientation: Orientation;
};

Additional Types

AccordionHeaderDataAttributes

Data attributes of Header.

typescript
declare namespace AccordionHeaderDataAttributes {
  /**
   * Indicates the index of the accordion item.
   * @type number
   */
  const index: 'data-index';
  /** Present when the accordion item is disabled. */
  const disabled: 'data-disabled';
  /** Present when the accordion item is open. */
  const open: 'data-open';
}

AccordionItemDataAttributes

Data attributes of Item.

typescript
declare namespace AccordionItemDataAttributes {
  /**
   * Indicates the index of the accordion item.
   * @type number
   */
  const index: 'data-index';
  /** Present when the accordion item is disabled. */
  const disabled: 'data-disabled';
  /** Present when the accordion item is open. */
  const open: 'data-open';
}

AccordionPanelCssVariables

CSS variables of Panel.

typescript
declare namespace AccordionPanelCssVariables {
  /**
   * The accordion panel's height.
   * @type number
   */
  const accordionPanelHeight: '--accordion-panel-height';
  /**
   * The accordion panel's width.
   * @type number
   */
  const accordionPanelWidth: '--accordion-panel-width';
}

AccordionPanelDataAttributes

Data attributes of Panel.

typescript
declare namespace AccordionPanelDataAttributes {
  /**
   * Indicates the index of the accordion item.
   * @type number
   */
  const index: 'data-index';
  /** Present when the accordion panel is open. */
  const open: 'data-open';
  /** Indicates the orientation of the accordion. */
  const orientation: 'data-orientation';
  /** Present when the accordion item is disabled. */
  const disabled: 'data-disabled';
  /** Present when the panel begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the panel is animating out. */
  const endingStyle: 'data-ending-style';
}

AccordionRootDataAttributes

Data attributes of Root.

typescript
declare namespace AccordionRootDataAttributes {
  /** Present when the accordion is disabled. */
  const disabled: 'data-disabled';
  /** Indicates the orientation of the accordion. */
  const orientation: 'data-orientation';
}

AccordionTriggerDataAttributes

Data attributes of Trigger.

typescript
declare namespace AccordionTriggerDataAttributes {
  /**
   * Indicates the index of the accordion item.
   * @type number
   */
  const index: 'data-index';
  /** Present when the accordion panel is open. */
  const panelOpen: 'data-panel-open';
  /** Present when the accordion item is disabled. */
  const disabled: 'data-disabled';
}

AccordionValue

typescript
type AccordionValue<Value = any> = Value[];

External Types

Orientation

typescript
type Orientation = 'horizontal' | 'vertical';

Export Groups

  • Accordion.Root: Accordion.Root, Accordion.Root.Value, Accordion.Root.State, Accordion.Root.Props, Accordion.Root.ChangeEventReason, Accordion.Root.ChangeEventDetails
  • Accordion.Item: Accordion.Item, Accordion.Item.State, Accordion.Item.Props, Accordion.Item.ChangeEventReason, Accordion.Item.ChangeEventDetails
  • Accordion.Header: Accordion.Header, Accordion.Header.State, Accordion.Header.Props
  • Accordion.Trigger: Accordion.Trigger, Accordion.Trigger.State, Accordion.Trigger.Props
  • Accordion.Panel: Accordion.Panel, Accordion.Panel.State, Accordion.Panel.Props
  • Default: AccordionRootDataAttributes, AccordionItemDataAttributes, AccordionHeaderDataAttributes, AccordionTriggerDataAttributes, AccordionPanelCssVariables, AccordionPanelDataAttributes, AccordionValue, AccordionRootState, AccordionRootProps, AccordionRootChangeEventReason, AccordionRootChangeEventDetails, AccordionItemState, AccordionItemProps, AccordionItemChangeEventReason, AccordionItemChangeEventDetails, AccordionHeaderState, AccordionHeaderProps, AccordionTriggerState, AccordionTriggerProps, AccordionPanelState, AccordionPanelProps

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

  • Accordion.Root.State: AccordionRootState
  • Accordion.Root.Props: AccordionRootProps
  • Accordion.Root.ChangeEventReason: AccordionRootChangeEventReason
  • Accordion.Root.ChangeEventDetails: AccordionRootChangeEventDetails
  • Accordion.Item.State: AccordionItemState
  • Accordion.Item.Props: AccordionItemProps
  • Accordion.Item.ChangeEventReason: AccordionItemChangeEventReason
  • Accordion.Item.ChangeEventDetails: AccordionItemChangeEventDetails
  • Accordion.Header.State: AccordionHeaderState
  • Accordion.Header.Props: AccordionHeaderProps
  • Accordion.Trigger.State: AccordionTriggerState
  • Accordion.Trigger.Props: AccordionTriggerProps
  • Accordion.Panel.State: AccordionPanelState
  • Accordion.Panel.Props: AccordionPanelProps

Src App (Docs) React Components Alert Dialog Page (`docs/src/app/(docs)/react/components/alert-dialog/page.mdx`)

Alert Dialog

A dialog that requires a user response to proceed.

import { DemoAlertDialogHero } from './demos/hero';

Anatomy

Import the component and assemble its parts:

jsx title="anatomy"
import { AlertDialog } from '@base-ui/react/alert-dialog';

<AlertDialog.Root>
  <AlertDialog.Trigger />
  <AlertDialog.Portal>
    <AlertDialog.Backdrop />
    <AlertDialog.Viewport>
      <AlertDialog.Popup>
        <AlertDialog.Title />
        <AlertDialog.Description />
        <AlertDialog.Close />
      </AlertDialog.Popup>
    </AlertDialog.Viewport>
  </AlertDialog.Portal>
</AlertDialog.Root>;

Examples

Open from a menu

In order to open a dialog using a menu, control the dialog state and open it imperatively using the onClick handler on the menu item.

import { DemoAlertDialogOpenFromMenu } from './demos/open-from-menu';

Close confirmation

This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.

To implement this, both dialogs should be controlled. The confirmation dialog may be opened when onOpenChange callback of the parent dialog receives a request to close. This way, the confirmation is automatically shown when the user clicks the backdrop, presses the Esc key, or clicks a close button.

Use the [data-nested-dialog-open] selector and the var(--nested-dialogs) CSS variable to customize the styling of the parent dialog. Backdrops of the child dialogs won't be rendered so that you can present the parent dialog in a clean way behind the one on top of it.

import { DemoDialogCloseConfirmation } from '../dialog/demos/close-confirmation';

Detached triggers

An alert dialog can be controlled by a trigger located either inside or outside the <AlertDialog.Root> component.
For simple, one-off interactions, place the <AlertDialog.Trigger> inside <AlertDialog.Root>, as shown in the example at the top of this page.

However, if defining the alert dialog's content next to its trigger is not practical, you can use a detached trigger.
This involves placing the <AlertDialog.Trigger> outside of <AlertDialog.Root> and linking them with a handle created by the AlertDialog.createHandle() function.

The imperative methods on the handle, such as open() and openWithPayload(), require an <AlertDialog.Root> using the same handle to be mounted.
Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.

jsx title="detached triggers"
const demoAlertDialog = AlertDialog.createHandle();

// @highlight
// @highlight-text "handle={demoAlertDialog}"
<AlertDialog.Trigger handle={demoAlertDialog}>Open</AlertDialog.Trigger>

// @highlight
// @highlight-text "handle={demoAlertDialog}"
<AlertDialog.Root handle={demoAlertDialog}>
  ...
</AlertDialog.Root>

import { DemoAlertDialogDetachedTriggersSimple } from './demos/detached-triggers-simple';

Multiple triggers

A single alert dialog can be opened by multiple trigger elements.
You can achieve this by using the same handle for several detached triggers, or by placing multiple <AlertDialog.Trigger> components inside a single <AlertDialog.Root>.

jsx title="multiple triggers within the root part"
<AlertDialog.Root>
  <AlertDialog.Trigger>Trigger 1</AlertDialog.Trigger>
  <AlertDialog.Trigger>Trigger 2</AlertDialog.Trigger>
  ...
</AlertDialog.Root>
jsx title="multiple detached triggers"
const demoAlertDialog = AlertDialog.createHandle();

<AlertDialog.Trigger handle={demoAlertDialog}>Trigger 1</AlertDialog.Trigger>
<AlertDialog.Trigger handle={demoAlertDialog}>Trigger 2</AlertDialog.Trigger>
<AlertDialog.Root handle={demoAlertDialog}>
  ...
</AlertDialog.Root>

The alert dialog can render different content depending on which trigger opened it.
This is achieved by passing a payload to the <AlertDialog.Trigger> and using the function-as-a-child pattern in <AlertDialog.Root>.

The payload can be strongly typed by providing a type argument to the createHandle() function:

jsx title="detached triggers with payload"
// @highlight
const demoAlertDialog = AlertDialog.createHandle<{ message: string }>();

// @highlight
// @highlight-text "payload"
<AlertDialog.Trigger handle={demoAlertDialog} payload={{ message: 'Trigger 1' }}>
  Trigger 1
</AlertDialog.Trigger>

// @highlight
// @highlight-text "payload"
<AlertDialog.Trigger handle={demoAlertDialog} payload={{ message: 'Trigger 2' }}>
  Trigger 2
</AlertDialog.Trigger>

<AlertDialog.Root handle={demoAlertDialog}>
  {({ payload }) => ( // @highlight-text "payload"
    <AlertDialog.Portal>
      <AlertDialog.Popup>
        <AlertDialog.Title>Alert dialog</AlertDialog.Title>
        {payload !== undefined && ( // @highlight-text "payload"
          <AlertDialog.Description>
            Confirming {payload.message} {/* @highlight-text "payload" */}
          </AlertDialog.Description>
        )}
      </AlertDialog.Popup>
    </AlertDialog.Portal>
  )}
</AlertDialog.Root>

Controlled mode with multiple triggers

You can control the alert dialog's open state externally using the open and onOpenChange props on <AlertDialog.Root>.
This allows you to manage the alert dialog's visibility based on your application's state.
When using multiple triggers, you have to manage which trigger is active with the triggerId prop on <AlertDialog.Root> and the id prop on each <AlertDialog.Trigger>.

Note that there is no separate onTriggerIdChange prop.
Instead, the onOpenChange callback receives an additional argument, eventDetails, which contains the trigger element that initiated the state change.

import { DemoAlertDialogDetachedTriggersControlled } from './demos/detached-triggers-controlled';

API reference

import { TypesAlertDialog } from './types';

Root

<TypesAlertDialog.Root />

Trigger

<TypesAlertDialog.Trigger />

Portal

<TypesAlertDialog.Portal />

Backdrop

<TypesAlertDialog.Backdrop />

Viewport

<TypesAlertDialog.Viewport />

<TypesAlertDialog.Popup />

Title

<TypesAlertDialog.Title />

Description

<TypesAlertDialog.Description />

Close

<TypesAlertDialog.Close />

createHandle

<TypesAlertDialog.createHandle />

Handle

<TypesAlertDialog.Handle />

export const metadata = {
keywords: [
'React Alert Dialog',
'Alert Dialog Component',
'Confirmation Modal',
'Warning Dialog',
'Blocking Modal',
'Interrupt Dialog',
'Destructive Action Confirm',
'Accessible Dialog',
'Headless React Components',
'React UI Overlay',
'Base UI',
],
};

Src App (Docs) React Components Alert Dialog Types (`docs/src/app/(docs)/react/components/alert-dialog/types.md`)

Alert Dialog

API Reference

Root

Groups all parts of the alert dialog.
Doesn't render its own HTML element.

Root Props:

Prop Type Default Description
defaultOpen boolean false Whether the dialog is initially open. To render a controlled dialog, use the open prop instead.
open boolean - Whether the dialog is currently open.
onOpenChange ((open: boolean, eventDetails: AlertDialog.Root.ChangeEventDetails) => void) - Event handler called when the alert dialog is opened or closed.
actionsRef React.RefObject<AlertDialog.Root.Actions | null> - A ref to imperative actions. unmount: Ends the closing phase of the alert dialog after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the alert dialog completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.close: Closes the alert dialog imperatively when called.
defaultTriggerId string | null - ID of the trigger that the dialog is associated with. This is useful in conjunction with the defaultOpen prop to create an initially open dialog.
handle AlertDialog.Handle - A handle to associate the alert dialog with a trigger. If specified, allows external triggers to control the alert dialog's open state. Can be created with the AlertDialog.createHandle() method.
onOpenChangeComplete ((open: boolean) => void) - Event handler called after any animations complete when the dialog is opened or closed.
triggerId string | null - ID of the trigger that the dialog is associated with. This is useful in conjunction with the open prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the open prop is not set).
children React.ReactNode | PayloadChildRenderFunction - The content of the dialog. This can be a regular React node or a render function that receives the payload of the active trigger.

Root.Props

Re-export of Root props.

Root.State

typescript
type AlertDialogRootState = {};

Root.Actions

typescript
type AlertDialogRootActions = { unmount: () => void; close: () => void };

Root.ChangeEventReason

typescript
type AlertDialogRootChangeEventReason =
  | 'trigger-press'
  | 'outside-press'
  | 'escape-key'
  | 'close-press'
  | 'focus-out'
  | 'imperative-action'
  | 'none';

Root.ChangeEventDetails

typescript
type AlertDialogRootChangeEventDetails = (
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'outside-press'; event: MouseEvent | PointerEvent | TouchEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'close-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'focus-out'; event: KeyboardEvent | FocusEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'none'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  /** Prevents the popup from unmounting until the `unmount` action is called. */
  preventUnmountOnClose: () => void;
};

Trigger

A button that opens the alert dialog.
Renders a `` element.

Trigger Props:

Prop Type Default Description
handle AlertDialog.Handle - A handle to associate the trigger with an alert dialog. Can be created with the AlertDialog.createHandle() method.
nativeButton boolean true Whether the component renders a native element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example,).
payload Payload - A payload to pass to the dialog when it is opened.
id string - ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot triggerId prop).
className string | ((state: AlertDialog.Trigger.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: AlertDialog.Trigger.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: AlertDialog.Trigger.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Trigger Data Attributes:

Attribute Type Description
data-popup-open - Present when the corresponding alert dialog is open.
data-disabled - Present when the trigger is disabled.

Trigger.Props

Re-export of Trigger props.

Trigger.State

typescript
type AlertDialogTriggerState = {
  /** Whether the trigger is currently disabled. */
  disabled: boolean;
  /** Whether the dialog is currently open and was opened by this trigger. */
  open: boolean;
};

Portal

A portal element that moves the popup to a different part of the DOM.
By default, the portal element is appended to . Renders a element.

Portal Props:

Prop Type Default Description
container HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null - A parent element to render the portal element into.
className string | ((state: AlertDialog.Portal.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: AlertDialog.Portal.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted boolean false Whether to keep the portal mounted in the DOM while the popup is hidden.
render ReactElement | ((props: HTMLProps, state: AlertDialog.Portal.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Portal.Props

Re-export of Portal props.

Portal.State

typescript
type AlertDialogPortalState = {};

Backdrop

An overlay displayed beneath the popup.
Renders a `` element.

Backdrop Props:

Prop Type Default Description
forceRender boolean false Whether the backdrop is forced to render even when nested.
className string | ((state: AlertDialog.Backdrop.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: AlertDialog.Backdrop.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: AlertDialog.Backdrop.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Backdrop Data Attributes:

Attribute Type Description
data-open - Present when the dialog is open.
data-closed - Present when the dialog is closed.
data-starting-style - Present when the dialog begins animating in.
data-ending-style - Present when the dialog is animating out.

Backdrop.Props

Re-export of Backdrop props.

Backdrop.State

typescript
type AlertDialogBackdropState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

A container for the dialog contents.
Renders a `` element.

Popup Props:

Prop Type Default Description
initialFocus boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null) - Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. false: Do not move focus.true: Move focus based on the default behavior (first tabbable element or popup).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.
finalFocus boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null) - Determines the element to focus when the dialog is closed. false: Do not move focus.true: Move focus based on the default behavior (trigger or previously focused element).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.
className string | ((state: AlertDialog.Popup.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: AlertDialog.Popup.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: AlertDialog.Popup.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Popup Data Attributes:

Attribute Type Description
data-open - Present when the dialog is open.
data-closed - Present when the dialog is closed.
data-nested - Present when the dialog is nested within another dialog.
data-nested-dialog-open - Present when the dialog has other open dialogs nested within it.
data-starting-style - Present when the dialog begins animating in.
data-ending-style - Present when the dialog is animating out.

Popup CSS Variables:

Variable Type Description
--nested-dialogs number Indicates how many dialogs are nested within.

Re-export of Popup props.

typescript
type AlertDialogPopupState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the dialog is nested within a parent dialog. */
  nested: boolean;
  /** Whether the dialog has nested dialogs open. */
  nestedDialogOpen: boolean;
};

Title

A heading that labels the dialog.
Renders an <h2> element.

Title Props:

Prop Type Default Description
className string | ((state: AlertDialog.Title.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: AlertDialog.Title.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: AlertDialog.Title.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Title.Props

Re-export of Title props.

Title.State

typescript
type AlertDialogTitleState = {};

Description

A paragraph with additional information about the dialog.
Renders a `` element.

Description Props:

Prop Type Default Description
className string | ((state: AlertDialog.Description.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: AlertDialog.Description.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: AlertDialog.Description.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Description.Props

Re-export of Description props.

Description.State

typescript
type AlertDialogDescriptionState = {};

Close

A button that closes the dialog.
Renders a `` element.

Close Props:

Prop Type Default Description
nativeButton boolean true Whether the component renders a native element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example,).
className string | ((state: AlertDialog.Close.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: AlertDialog.Close.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: AlertDialog.Close.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Close Data Attributes:

Attribute Type Description
data-disabled - Present when the button is disabled.

Close.Props

Re-export of Close props.

Close.State

typescript
type AlertDialogCloseState = {
  /** Whether the button is currently disabled. */
  disabled: boolean;
};

Viewport

A positioning container for the dialog popup that can be made scrollable.
Renders a `` element.

Viewport Props:

Prop Type Default Description
className string | ((state: AlertDialog.Viewport.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: AlertDialog.Viewport.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: AlertDialog.Viewport.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Viewport Data Attributes:

Attribute Type Description
data-open - Present when the dialog is open.
data-closed - Present when the dialog is closed.
data-nested - Present when the dialog is nested within another dialog.
data-nested-dialog-open - Present when the dialog has other open dialogs nested within it.
data-starting-style - Present when the dialog begins animating in.
data-ending-style - Present when the dialog is animating out.

Viewport.Props

Re-export of Viewport props.

Viewport.State

typescript
type AlertDialogViewportState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the dialog is nested within another dialog. */
  nested: boolean;
  /** Whether the dialog has nested dialogs open. */
  nestedDialogOpen: boolean;
};

createHandle

Creates a new handle to connect an AlertDialog.Root with detached AlertDialog.Trigger components.

Return Value:

tsx
type ReturnValue = AlertDialog.Handle<Payload>;

Handle

Controls an Alert Dialog imperatively and associates detached AlertDialog.Trigger components with
an AlertDialog.Root. Create one with AlertDialog.createHandle() and pass it to the handle
prop of the root and of any triggers rendered outside of it.

The imperative methods take effect only while a root using this handle is mounted; calls made
before a root attaches (or after it unmounts) are ignored.

Properties:

Property Type Modifiers Description
isOpen boolean readonly Whether the dialog is currently open. Returns false while no root is attached to the handle.

Methods:

typescript
function open(triggerId: string | null): void;

Opens the dialog, optionally associating it with a trigger.

This method should only be called in an event handler or an effect (not during rendering).

typescript
function openWithPayload(payload: Payload): void;

Opens the dialog with the given payload, without associating it with any trigger.

This method should only be called in an event handler or an effect (not during rendering).

typescript
function close(): void;

Closes the dialog.

This method should only be called in an event handler or an effect (not during rendering).

Additional Types

AlertDialogBackdropDataAttributes

Data attributes of Backdrop.

typescript
declare namespace AlertDialogBackdropDataAttributes {
  /** Present when the dialog is open. */
  const open: 'data-open';
  /** Present when the dialog is closed. */
  const closed: 'data-closed';
  /** Present when the dialog begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the dialog is animating out. */
  const endingStyle: 'data-ending-style';
}

AlertDialogCloseDataAttributes

Data attributes of Close.

typescript
declare namespace AlertDialogCloseDataAttributes {
  /** Present when the button is disabled. */
  const disabled: 'data-disabled';
}

AlertDialogPopupCssVariables

CSS variables of Popup.

typescript
declare namespace AlertDialogPopupCssVariables {
  /**
   * Indicates how many dialogs are nested within.
   * @type number
   */
  const nestedDialogs: '--nested-dialogs';
}

AlertDialogPopupDataAttributes

Data attributes of Popup.

typescript
declare namespace AlertDialogPopupDataAttributes {
  /** Present when the dialog is open. */
  const open: 'data-open';
  /** Present when the dialog is closed. */
  const closed: 'data-closed';
  /** Present when the dialog begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the dialog is animating out. */
  const endingStyle: 'data-ending-style';
  /** Present when the dialog is nested within another dialog. */
  const nested: 'data-nested';
  /** Present when the dialog has other open dialogs nested within it. */
  const nestedDialogOpen: 'data-nested-dialog-open';
}

AlertDialogTriggerDataAttributes

Data attributes of Trigger.

typescript
declare namespace AlertDialogTriggerDataAttributes {
  /** Present when the trigger is disabled. */
  const disabled: 'data-disabled';
  /** Present when the corresponding alert dialog is open. */
  const popupOpen: 'data-popup-open';
}

AlertDialogViewportDataAttributes

Data attributes of Viewport.

typescript
declare namespace AlertDialogViewportDataAttributes {
  /** Present when the dialog is open. */
  const open: 'data-open';
  /** Present when the dialog is closed. */
  const closed: 'data-closed';
  /** Present when the dialog begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the dialog is animating out. */
  const endingStyle: 'data-ending-style';
  /** Present when the dialog is nested within another dialog. */
  const nested: 'data-nested';
  /** Present when the dialog has other open dialogs nested within it. */
  const nestedDialogOpen: 'data-nested-dialog-open';
}

External Types

PayloadChildRenderFunction

typescript
type PayloadChildRenderFunction = (arg: { payload: unknown | undefined }) => ReactNode;

InteractionType

typescript
type InteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard' | '';

Export Groups

  • AlertDialog.Root: AlertDialog.Root, AlertDialog.Root.State, AlertDialog.Root.Props, AlertDialog.Root.Actions, AlertDialog.Root.ChangeEventReason, AlertDialog.Root.ChangeEventDetails
  • AlertDialog.Backdrop: AlertDialog.Backdrop, AlertDialog.Backdrop.Props, AlertDialog.Backdrop.State
  • AlertDialog.Close: AlertDialog.Close, AlertDialog.Close.Props, AlertDialog.Close.State
  • AlertDialog.Description: AlertDialog.Description, AlertDialog.Description.Props, AlertDialog.Description.State
  • AlertDialog.Popup: AlertDialog.Popup, AlertDialog.Popup.Props, AlertDialog.Popup.State
  • AlertDialog.Portal: AlertDialog.Portal, AlertDialog.Portal.State, AlertDialog.Portal.Props
  • AlertDialog.Title: AlertDialog.Title, AlertDialog.Title.Props, AlertDialog.Title.State
  • AlertDialog.Trigger: AlertDialog.Trigger, AlertDialog.Trigger.Props, AlertDialog.Trigger.State
  • AlertDialog.Viewport: AlertDialog.Viewport, AlertDialog.Viewport.State, AlertDialog.Viewport.Props
  • AlertDialog.Handle
  • AlertDialog.createHandle
  • Default: AlertDialogBackdropProps, AlertDialogBackdropState, AlertDialogCloseProps, AlertDialogCloseState, AlertDialogDescriptionProps, AlertDialogDescriptionState, AlertDialogPopupProps, AlertDialogPopupState, AlertDialogPortalProps, AlertDialogPortalState, AlertDialogTitleProps, AlertDialogTitleState, AlertDialogViewportProps, AlertDialogViewportState, AlertDialogBackdropDataAttributes, AlertDialogCloseDataAttributes, AlertDialogPopupCssVariables, AlertDialogPopupDataAttributes, AlertDialogTriggerDataAttributes, AlertDialogViewportDataAttributes, AlertDialogRootState, AlertDialogRootProps, AlertDialogRootActions, AlertDialogRootChangeEventReason, AlertDialogRootChangeEventDetails, AlertDialogTriggerProps, AlertDialogTriggerState

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

  • AlertDialog.Root.State: AlertDialogRootState
  • AlertDialog.Root.Props: AlertDialogRootProps
  • AlertDialog.Root.Actions: AlertDialogRootActions
  • AlertDialog.Root.ChangeEventReason: AlertDialogRootChangeEventReason
  • AlertDialog.Root.ChangeEventDetails: AlertDialogRootChangeEventDetails
  • AlertDialog.Backdrop.Props: AlertDialogBackdropProps
  • AlertDialog.Backdrop.State: AlertDialogBackdropState
  • AlertDialog.Close.Props: AlertDialogCloseProps
  • AlertDialog.Close.State: AlertDialogCloseState
  • AlertDialog.Description.Props: AlertDialogDescriptionProps
  • AlertDialog.Description.State: AlertDialogDescriptionState
  • AlertDialog.Popup.Props: AlertDialogPopupProps
  • AlertDialog.Popup.State: AlertDialogPopupState
  • AlertDialog.Portal.State: AlertDialogPortalState
  • AlertDialog.Portal.Props: AlertDialogPortalProps
  • AlertDialog.Title.Props: AlertDialogTitleProps
  • AlertDialog.Title.State: AlertDialogTitleState
  • AlertDialog.Trigger.Props: AlertDialogTriggerProps
  • AlertDialog.Trigger.State: AlertDialogTriggerState
  • AlertDialog.Viewport.State: AlertDialogViewportState
  • AlertDialog.Viewport.Props: AlertDialogViewportProps

Src App (Docs) React Components Autocomplete Page (`docs/src/app/(docs)/react/components/autocomplete/page.mdx`)

Autocomplete

An input that suggests options as you type.

import { DemoAutocompleteHero } from './demos/hero';

Usage guidelines

  • Avoid when selection state is needed: Use Combobox instead of Autocomplete if the selection should be remembered and the input value cannot be custom. Unlike Combobox, Autocomplete's input can contain free-form text, as its suggestions only optionally autocomplete the text.
  • Can be used for filterable command pickers: The input can be used as a filter for command items that perform an action when clicked when rendered inside the popup.
  • Form controls must have an accessible name: It can be created using a <label> element or the Field component. See the forms guide.
  • Closing animations: The popup stays rendered until its closing animation finishes. See JavaScript animations for animating it with Motion and for manual control.

Anatomy

Import the components and place them together:

jsx title="anatomy"
import { Autocomplete } from '@base-ui/react/autocomplete';

<Autocomplete.Root>
  <Autocomplete.InputGroup>
    <Autocomplete.Input />
    <Autocomplete.Trigger />
    <Autocomplete.Icon />
    <Autocomplete.Clear />
    <Autocomplete.Value />
  </Autocomplete.InputGroup>

  <Autocomplete.Portal>
    <Autocomplete.Backdrop />
    <Autocomplete.Positioner>
      <Autocomplete.Popup>
        <Autocomplete.Arrow />

        <Autocomplete.Status />
        <Autocomplete.Empty />

        <Autocomplete.List>
          <Autocomplete.Row>
            <Autocomplete.Item />
          </Autocomplete.Row>

          <Autocomplete.Separator />

          <Autocomplete.Group>
            <Autocomplete.GroupLabel />
          </Autocomplete.Group>

          <Autocomplete.Collection />
        </Autocomplete.List>
      </Autocomplete.Popup>
    </Autocomplete.Positioner>
  </Autocomplete.Portal>
</Autocomplete.Root>;

Item values

Each <Autocomplete.Item> takes a value prop identifying it. Pass the item being rendered, so that props like itemToStringValue receive it.

Examples

Load items asynchronously while typing and render custom status content.

import { DemoAutocompleteAsync } from './demos/async';

Inline autocomplete

Autofill the input with the highlighted item while navigating with arrow keys using the mode prop. Accepts aria-autocomplete values list, both, inline, or none.

import { DemoAutocompleteInline } from './demos/inline';

Grouped

Organize related options with <Autocomplete.Group> and <Autocomplete.GroupLabel> to add section headings inside the popup.

Groups are represented by an array of objects with an items property, which itself is an array of individual items for each group. An extra property, such as value, can be provided for the heading text when rendering the group label.

tsx title="example"
interface ProduceGroupItem {
  value: string;
  // @highlight
  items: string[];
}

const groups: ProduceGroupItem[] = [
  {
    value: 'Fruits',
    // @highlight
    items: ['Apple', 'Banana', 'Orange'],
  },
  {
    value: 'Vegetables',
    // @highlight
    items: ['Carrot', 'Lettuce', 'Spinach'],
  },
];

import { DemoAutocompleteGrouped } from './demos/grouped';

Fuzzy matching

Use fuzzy matching to find relevant results even when the query doesn't exactly match the item text.

import { DemoAutocompleteFuzzyMatching } from './demos/fuzzy-matching';

Limit results

Limit the number of visible items using the limit prop and guide users to refine their query using <Autocomplete.Status>.

import { DemoAutocompleteLimit } from './demos/limit';

Auto highlight

The first matching item can be automatically highlighted as the user types by specifying the autoHighlight prop on <Autocomplete.Root>. Set the prop's value to "always" if the highlight should always be present, such as when the list is rendered inline within a dialog.

The prop can be combined with the keepHighlight and highlightItemOnHover props to configure how the highlight behaves during mouse interactions.

import { DemoAutocompleteAutoHighlight } from './demos/auto-highlight';

Command palette

Use the autocomplete input to filter a list of command items that perform an action when clicked.

import { DemoAutocompleteCommandPalette } from './demos/command-palette';

Grid layout

Display items in a grid layout, wrapping each row in <Autocomplete.Row> components.

import { DemoAutocompleteGrid } from './demos/grid';

Virtualized

Efficiently handle large datasets using a virtualization library like @tanstack/react-virtual.

import { DemoAutocompleteVirtualized } from './demos/virtualized';

Memoizing items

Memoizing each item is a simpler alternative to virtualization for datasets up to roughly 1,000 items. Wrap each item in React.memo and pass the item as a prop so unchanged items skip re-rendering. While memoization speeds up typing, it does not speed up opening; with a large enough number of items, the mount cost dominates, and virtualization becomes necessary to keep the open interaction fast on low-end devices.

tsx title="memoizing list items"
interface Suggestion {
  id: string;
  label: string;
  description: string;
}

const SuggestionItem = React.memo(function SuggestionItem({ item }: { item: Suggestion }) {
  return (
    <Autocomplete.Item value={item}>
      <span>{item.label}</span>
      <span>{item.description}</span>
    </Autocomplete.Item>
  );
});

<Autocomplete.List>
  {(item: Suggestion) => <SuggestionItem key={item.id} item={item} />}
</Autocomplete.List>;

API reference

import { TypesAutocomplete } from './types';

Root

<TypesAutocomplete.Root />

Value

<TypesAutocomplete.Value />

Input

<TypesAutocomplete.Input />

InputGroup

<TypesAutocomplete.InputGroup />

Trigger

<TypesAutocomplete.Trigger />

Icon

<TypesAutocomplete.Icon />

Clear

<TypesAutocomplete.Clear />

List

<TypesAutocomplete.List />

Portal

<TypesAutocomplete.Portal />

Backdrop

<TypesAutocomplete.Backdrop />

Positioner

<TypesAutocomplete.Positioner />

<TypesAutocomplete.Popup />

Arrow

<TypesAutocomplete.Arrow />

Status

<TypesAutocomplete.Status />

Empty

<TypesAutocomplete.Empty />

Collection

<TypesAutocomplete.Collection />

Row

<TypesAutocomplete.Row />

Item

<TypesAutocomplete.Item />

Group

<TypesAutocomplete.Group />

GroupLabel

<TypesAutocomplete.GroupLabel />

Separator

<TypesAutocomplete.Separator />

useFilter

Matches items against a query using Intl.Collator for robust string matching.
This hook is used when externally filtering items.

<TypesAutocomplete.useFilter hideDescription />

useFilteredItems

Returns the internally filtered items when called inside <Autocomplete.Root>.

<TypesAutocomplete.useFilteredItems hideDescription />

export const metadata = {
keywords: [
'React Autocomplete',
'Autocomplete Component',
'Search Suggestions',
'Filterable Input',
'Async Autocomplete',
'Typeahead',
'Lookahead',
'Autosuggest',
'Incremental Search',
'Predictive Text',
'Search Input',
'Accessible Combobox',
'Headless React Components',
'Base UI',
],
};

Src App (Docs) React Components Autocomplete Types (`docs/src/app/(docs)/react/components/autocomplete/types.md`)

Autocomplete

API Reference

Root

Groups all parts of the autocomplete.
Doesn't render its own HTML element.

Root Props:

Prop Type Default Description
name string - Identifies the field when a form is submitted.
defaultValue string | number | string[] - The uncontrolled input value of the autocomplete when it's initially rendered. To render a controlled autocomplete, use the value prop instead.
value string | string[] | number - The input value of the autocomplete. Use when controlled.
onValueChange ((value: string, eventDetails: Autocomplete.Root.ChangeEventDetails) => void) - Event handler called when the input value of the autocomplete changes.
defaultOpen boolean false Whether the popup is initially open. To render a controlled popup, use the open prop instead.
open boolean - Whether the popup is currently open. Use when controlled.
onOpenChange ((open: boolean, eventDetails: Autocomplete.Root.OpenChangeEventDetails) => void) - Event handler called when the popup is opened or closed.
autoHighlight boolean | 'always' false Whether the first matching item is highlighted automatically. true: highlight after the user types and keep the highlight while the query changes.'always': always highlight the first item.
keepHighlight boolean false Whether the highlighted item should be preserved when the pointer leaves the list.
highlightItemOnHover boolean true Whether moving the pointer over items should highlight them. Disabling this prop allows CSS :hover to be differentiated from the :focus (data-highlighted) state.
actionsRef React.RefObject<Autocomplete.Root.Actions | null> - A ref to imperative actions. unmount: Ends the closing phase of the autocomplete after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the autocomplete completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.close: Closes the autocomplete imperatively when called.
filter ((item: ItemValue, query: string, itemToString?: ((item: ItemValue) => string)) => boolean) | null - AutocompleteFilter function used to match items against the input query.
filteredItems any[] | Group<any>[] | ItemValue[] | Group[] - Filtered items to display in the list. When provided, the list uses these items instead of filtering the items prop internally. When items is also provided, this array must preserve its flat or grouped structure. Nullish entries are not supported, as in items. Use when you want to control filtering logic externally with the useFilter() hook.
form string - Identifies the form that owns the internal input. Useful when the autocomplete is rendered outside the form.
grid boolean false Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
inline boolean false Whether the list is rendered inline without using the component's own popup. Specify open unconditionally in conjunction with this prop so the list is considered visible: <Autocomplete.Root inline open>
itemToStringValue ((itemValue: ItemValue) => string) - When the item values are objects (<Autocomplete.Item value={object}>), this function converts the object value to a string representation for both display in the input and form submission. If the shape of the object is { value, label }, the label will be used automatically without needing to specify this prop.
items ({ items: any[] })[] | ItemValue[] - The items to be displayed in the list. Can be either a flat array of items or an array of groups with items. Nullish entries are not supported: remove them from the data before passing it.
limit number -1 The maximum number of items to display in the list.
locale Intl.LocalesArgument - The locale to use for string comparison. Defaults to the user's runtime locale.
loopFocus boolean true Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing ArrowDown again from the input, or the last item can be reached by pressing ArrowUp from the input. The input is always included in the focus loop per ARIA Authoring Practices. When disabled, focus does not move when on the last element and the user presses ArrowDown, or when on the first element and the user presses ArrowUp.
modal boolean false Determines if the popup enters a modal state when open. true: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.false: user interaction with the rest of the document is allowed. On touch devices, a true modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
mode 'list' | 'both' | 'inline' | 'none' 'list' Controls how the autocomplete behaves with respect to list filtering and inline autocompletion. list (default): items are dynamically filtered based on the input value. The input value does not change based on the active item.both: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion).inline: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion).none: items are static (not filtered), and the input value will not change based on the active item.
onItemHighlighted ((highlightedValue: ItemValue | undefined, eventDetails: Autocomplete.Root.HighlightEventDetails) => void) - Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or undefined if no item is highlighted) and event details with a reason property describing why the highlight changed. The reason can be: 'keyboard': the highlight changed due to keyboard navigation.'pointer': the highlight changed due to pointer hovering. The event may be a MouseEvent rather than a PointerEvent.'none': the highlight changed for another reason, such as typing, autoHighlight, the item list changing, or the popup opening or closing.
onOpenChangeComplete ((open: boolean) => void) - Event handler called after any animations complete when the popup is opened or closed.
openOnInputClick boolean false Whether the popup opens when clicking the input.
submitOnItemClick boolean false Whether clicking an item should submit the autocomplete's owning form. By default, clicking an item via a pointer or Enter key does not submit the owning form. Useful when the autocomplete is used as a single-field form search input.
virtualized boolean false Whether the items are being externally virtualized.
disabled boolean false Whether the component should ignore user interaction.
readOnly boolean false Whether the user should be unable to choose a different option from the popup.
required boolean false Whether the user must choose a value before submitting a form.
inputRef React.Ref<HTMLInputElement> - A ref to the hidden input element.
id string - The id of the component.
children React.ReactNode - -

Root.Props

Re-export of Root props.

Root.State

typescript
type AutocompleteRootState = {};

Root.Actions

typescript
type AutocompleteRootActions = { unmount: () => void; close: () => void };

Root.ChangeEventReason

typescript
type AutocompleteRootChangeEventReason =
  | 'trigger-press'
  | 'input-press'
  | 'outside-press'
  | 'item-press'
  | 'close-press'
  | 'escape-key'
  | 'list-navigation'
  | 'focus-out'
  | 'input-change'
  | 'input-clear'
  | 'clear-press'
  | 'chip-remove-press'
  | 'cancel-open'
  | 'imperative-action'
  | 'none';

Root.ChangeEventDetails

text
/* Detailed source-code truncated for AI context efficiency. */

Root.HighlightEventReason

typescript
type AutocompleteRootHighlightEventReason = 'keyboard' | 'pointer' | 'none';

Root.HighlightEventDetails

typescript
type AutocompleteRootHighlightEventDetails =
  | { reason: 'none'; event: Event; index: number }
  | { reason: 'keyboard'; event: KeyboardEvent; index: number }
  | { reason: 'pointer'; event: MouseEvent | PointerEvent; index: number };

Root.OpenChangeEventDetails

text
/* Detailed source-code truncated for AI context efficiency. */

Trigger

A button that opens the popup.
Renders a `` element.

Trigger Props:

Prop Type Default Description
nativeButton boolean true Whether the component renders a native element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example,).
disabled boolean false Whether the component should ignore user interaction.
className string | ((state: Autocomplete.Trigger.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Trigger.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Trigger.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Trigger Data Attributes:

Attribute Type Description
data-popup-open - Present when the corresponding popup is open.
data-popup-side 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null Indicates which side the corresponding popup is positioned relative to its anchor.
data-list-empty - Present when the corresponding items list is empty.
data-pressed - Present when the trigger is pressed.
data-disabled - Present when the component is disabled.
data-readonly - Present when the component is readonly.
data-required - Present when the component is required.
data-valid - Present when the component is in a valid state (when wrapped in Field.Root).
data-invalid - Present when the component is in an invalid state (when wrapped in Field.Root).
data-dirty - Present when the component's value has changed (when wrapped in Field.Root).
data-touched - Present when the component has been touched (when wrapped in Field.Root).
data-filled - Present when the component has a value (when wrapped in Field.Root).
data-focused - Present when the trigger is focused (when wrapped in Field.Root).

Trigger.Props

Re-export of Trigger props.

Trigger.State

typescript
type AutocompleteTriggerState = {
  /** Whether the popup is open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Indicates which side the corresponding popup is positioned relative to its anchor. */
  popupSide: Side | null;
  /** Present when the corresponding items list is empty. */
  listEmpty: boolean;
  /** Whether the component should ignore user edits. */
  readOnly: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Value

The current value of the autocomplete.
Doesn't render its own HTML element.

Value Props:

Prop Type Default Description
children React.ReactNode | ((value: string) => React.ReactNode) - -

Value.Props

Re-export of Value props.

Value.State

typescript
type AutocompleteValueState = {};

Input

A text input to search for items in the list.
Renders an `` element.

Input Props:

Prop Type Default Description
disabled boolean false Whether the component should ignore user interaction.
className string | ((state: Autocomplete.Input.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Input.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Input.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Input Data Attributes:

Attribute Type Description
data-popup-open - Present when the corresponding popup is open.
data-popup-side 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null Indicates which side the corresponding popup is positioned relative to its anchor.
data-list-empty - Present when the corresponding items list is empty.
data-pressed - Present when the input is pressed.
data-disabled - Present when the component is disabled.
data-readonly - Present when the component is readonly.
data-required - Present when the component is required.
data-valid - Present when the component is in a valid state (when wrapped in Field.Root).
data-invalid - Present when the component is in an invalid state (when wrapped in Field.Root).
data-dirty - Present when the component's value has changed (when wrapped in Field.Root).
data-touched - Present when the component has been touched (when wrapped in Field.Root).
data-filled - Present when the component has a value (when wrapped in Field.Root).
data-focused - Present when the input is focused (when wrapped in Field.Root).

Input.Props

Re-export of Input props.

Input.State

typescript
type AutocompleteInputState = {
  /** Whether the corresponding popup is open. */
  open: boolean;
  /** Indicates which side the corresponding popup is positioned relative to its anchor. */
  popupSide: Side | null;
  /** Present when the corresponding items list is empty. */
  listEmpty: boolean;
  /** Whether the component should ignore user edits. */
  readOnly: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Icon

An icon that indicates that the trigger button opens the popup.
Renders a `` element.

Icon Props:

Prop Type Default Description
className string | ((state: Autocomplete.Icon.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Icon.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Icon.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Icon.Props

Re-export of Icon props.

Icon.State

typescript
type AutocompleteIconState = {};

Clear

Clears the value when clicked.
Renders a `` element.

Clear Props:

Prop Type Default Description
nativeButton boolean true Whether the component renders a native element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example,).
disabled boolean false Whether the component should ignore user interaction.
className string | ((state: Autocomplete.Clear.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Clear.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted boolean false Whether the component should remain mounted in the DOM when not visible.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Clear.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Clear Data Attributes:

Attribute Type Description
data-popup-open - Present when the corresponding popup is open.
data-disabled - Present when the button is disabled.
data-visible - Present when the clear button is visible.
data-starting-style - Present when the button begins animating in.
data-ending-style - Present when the button is animating out.

Clear.Props

Re-export of Clear props.

Clear.State

typescript
type AutocompleteClearState = {
  /** Whether the popup is open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the clear button should be visible. */
  visible: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

List

A list container for the items.
Renders a `` element.

List Props:

Prop Type Default Description
children React.ReactNode | ((item: any, index: number) => React.ReactNode) - -
className string | ((state: Autocomplete.List.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.List.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.List.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

List.Props

Re-export of List props.

List.State

typescript
type AutocompleteListState = {
  /** Whether the list is empty. */
  empty: boolean;
};

Portal

A portal element that moves the popup to a different part of the DOM.
By default, the portal element is appended to . Renders a element.

Portal Props:

Prop Type Default Description
container HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null - A parent element to render the portal element into.
className string | ((state: Autocomplete.Portal.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Portal.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted boolean false Whether to keep the portal mounted in the DOM while the popup is hidden.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Portal.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Portal.Props

Re-export of Portal props.

Portal.State

typescript
type AutocompletePortalState = {};

Backdrop

An overlay displayed beneath the popup.
Renders a `` element.

Backdrop Props:

Prop Type Default Description
className string | ((state: Autocomplete.Backdrop.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Backdrop.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Backdrop.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Backdrop Data Attributes:

Attribute Type Description
data-open - Present when the popup is open.
data-closed - Present when the popup is closed.
data-starting-style - Present when the popup begins animating in.
data-ending-style - Present when the popup is animating out.

Backdrop.Props

Re-export of Backdrop props.

Backdrop.State

typescript
type AutocompleteBackdropState = {
  /** Whether the popup is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

Positioner

Positions the popup against the trigger.
Renders a `` element.

Positioner Props:

Prop Type Default Description
disableAnchorTracking boolean false Whether to disable the popup from tracking any layout shift of its positioning anchor.
align Align 'center' How to align the popup relative to the specified side.
alignOffset number | OffsetFunction 0 Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a data object parameter with the following properties: data.anchor: the dimensions of the anchor element with properties width and height.data.positioner: the dimensions of the positioner element with properties width and height.data.side: which side of the anchor element the positioner is aligned against.data.align: how the positioner is aligned relative to the specified side.
side Side 'bottom' Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffset number | OffsetFunction 0 Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a data object parameter with the following properties: data.anchor: the dimensions of the anchor element with properties width and height.data.positioner: the dimensions of the positioner element with properties width and height.data.side: which side of the anchor element the positioner is aligned against.data.align: how the positioner is aligned relative to the specified side.
arrowPadding number 5 Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
anchor Element | VirtualElement | React.RefObject<Element | null> | (() => Element | VirtualElement | null) | null - An element to position the popup against. By default, the popup will be positioned against the trigger.
collisionAvoidance CollisionAvoidance - Determines how to handle collisions when positioning the popup. side controls overflow on the preferred placement axis (top/bottom or left/right): 'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right).'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.'none': do not correct side-axis overflow. align controls overflow on the alignment axis (start/center/end): 'flip': keep side, but swap start and end when the requested alignment overflows.'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.'none': do not correct alignment-axis overflow. fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: 'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR).'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR).'none': do not fallback to the perpendicular axis. When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is omitted, it defaults to 'flip'.
collisionBoundary Boundary 'clipping-ancestors' An element or a rectangle that delimits the area that the popup is confined to.
collisionPadding Padding 5 Additional space to maintain from the edge of the collision boundary.
sticky boolean false Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
positionMethod 'absolute' | 'fixed' 'absolute' Determines which CSS position property to use.
className string | ((state: Autocomplete.Positioner.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Positioner.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Positioner.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

alignOffset Prop Example:

jsx
<Positioner
  alignOffset={({ side, align, anchor, positioner }) => {
    return side === 'top' || side === 'bottom' ? anchor.width : anchor.height;
  }}
/>

sideOffset Prop Example:

jsx
<Positioner
  sideOffset={({ side, align, anchor, positioner }) => {
    return side === 'top' || side === 'bottom' ? anchor.height : anchor.width;
  }}
/>

collisionAvoidance Prop Example:

jsx
<Positioner
  collisionAvoidance={{
    side: 'shift',
    align: 'shift',
    fallbackAxisSide: 'none',
  }}
/>

Positioner Data Attributes:

Attribute Type Description
data-open - Present when the popup is open.
data-closed - Present when the popup is closed.
data-anchor-hidden - Present when the anchor is hidden.
data-align 'start' | 'center' | 'end' Indicates how the popup is aligned relative to specified side.
data-empty - Present when the items list is empty.
data-side 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' Indicates which side the popup is positioned relative to the trigger.

Positioner CSS Variables:

Variable Type Description
--anchor-height number The anchor's height.
--anchor-width number The anchor's width.
--available-height number The available height between the trigger and the edge of the viewport.
--available-width number The available width between the trigger and the edge of the viewport.
--transform-origin string The coordinates that this element is anchored to. Used for animations and transitions.

Positioner.Props

Re-export of Positioner props.

Positioner.State

typescript
type AutocompletePositionerState = {
  /** Whether the popup is currently open. */
  open: boolean;
  /** The side of the anchor the component is placed on. */
  side: Side;
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the anchor element is hidden. */
  anchorHidden: boolean;
  /** Whether there are no items to display. */
  empty: boolean;
};

A container for the list.
Renders a `` element.

Popup Props:

Prop Type Default Description
initialFocus boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null) - Determines the element to focus when the popup is opened. false: Do not move focus.true: Move focus based on the default behavior (first tabbable element or popup).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing.
finalFocus boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null) - Determines the element to focus when the popup is closed. false: Do not move focus.true: Move focus based on the default behavior (trigger or previously focused element).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing.
className string | ((state: Autocomplete.Popup.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Popup.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Popup.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Popup Data Attributes:

Attribute Type Description
data-open - Present when the popup is open.
data-closed - Present when the popup is closed.
data-anchor-hidden - Present when the anchor is hidden.
data-align 'start' | 'center' | 'end' Indicates how the popup is aligned relative to specified side.
data-empty - Present when the items list is empty.
data-side 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' Indicates which side the popup is positioned relative to the trigger.
data-starting-style - Present when the popup begins animating in.
data-ending-style - Present when the popup is animating out.

Re-export of Popup props.

typescript
type AutocompletePopupState = {
  /** Whether the component is open. */
  open: boolean;
  /** The side of the anchor the component is placed on. */
  side: Side;
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the anchor element is hidden. */
  anchorHidden: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether there are no items to display. */
  empty: boolean;
};

Arrow

Displays an element positioned against the anchor.
Renders a `` element.

Arrow Props:

Prop Type Default Description
className string | ((state: Autocomplete.Arrow.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Arrow.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Arrow.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Arrow Data Attributes:

Attribute Type Description
data-open - Present when the popup is open.
data-closed - Present when the popup is closed.
data-uncentered - Present when the arrow is uncentered.
data-align 'start' | 'center' | 'end' Indicates how the popup is aligned relative to specified side.
data-side 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' Indicates which side the popup is positioned relative to the trigger.

Arrow.Props

Re-export of Arrow props.

Arrow.State

typescript
type AutocompleteArrowState = {
  /** Whether the popup is currently open. */
  open: boolean;
  /** The side of the anchor the component is placed on. */
  side: Side;
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the arrow cannot be centered on the anchor. */
  uncentered: boolean;
};

Item

An individual item in the list.
Renders a `` element.

Item Props:

Prop Type Default Description
value any null A unique value that identifies this item.
onClick ((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) - An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing Enter with the keyboard if the item is highlighted when the Input or List element has focus.
index number - The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.
nativeButton boolean false Whether the component renders a native `` element when replacing it via the render prop. Set to true if the rendered element is a native button.
disabled boolean false Whether the component should ignore user interaction.
children React.ReactNode - -
className string | ((state: Autocomplete.Item.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Item.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Item.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Item Data Attributes:

Attribute Type Description
data-highlighted - Present when the item is highlighted.
data-disabled - Present when the item is disabled.

Item.Props

Re-export of Item props.

Item.State

typescript
type AutocompleteItemState = {
  /** Whether the item should ignore user interaction. */
  disabled: boolean;
  /** Whether the item is highlighted. */
  highlighted: boolean;
};

Group

Groups related items with the corresponding label.
Renders a `` element.

Group Props:

Prop Type Default Description
items any[] - Items to be rendered within this group. When provided, child Collection components will use these items.
className string | ((state: Autocomplete.Group.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Group.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Group.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Group.Props

Re-export of Group props.

Group.State

typescript
type AutocompleteGroupState = {};

GroupLabel

An accessible label that is automatically associated with its parent group.
Renders a `` element.

GroupLabel Props:

Prop Type Default Description
className string | ((state: Autocomplete.GroupLabel.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.GroupLabel.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.GroupLabel.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

GroupLabel.Props

Re-export of GroupLabel props.

GroupLabel.State

typescript
type AutocompleteGroupLabelState = {};

Separator

A visual separator between items or groups.
Renders a `` element.

Separator Props:

Prop Type Default Description
orientation Orientation 'horizontal' The orientation of the separator.
className string | ((state: Autocomplete.Separator.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Separator.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Separator.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Separator Data Attributes:

Attribute Type Description
data-orientation 'horizontal' | 'vertical' Indicates the orientation of the separator.

Separator.Props

Re-export of Separator props.

Separator.State

typescript
type AutocompleteSeparatorState = {
  /** The orientation of the separator. */
  orientation: Orientation;
};

Status

Displays a status message whose content changes are announced politely to screen readers.
Useful for conveying the status of an asynchronously loaded list.
This component's root element must remain mounted in the DOM to announce
changes consistently across screen readers. Avoid hiding or removing the
component itself with display: none, hidden, aria-hidden, or conditional
rendering. Prefer updating or conditionally rendering its children instead.
Renders a `` element.

Status Props:

Prop Type Default Description
className string | ((state: Autocomplete.Status.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Status.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Status.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Status.Props

Re-export of Status props.

Status.State

typescript
type AutocompleteStatusState = {};

Empty

Renders its children only when the list is empty.
Requires the items prop on the root component.
Announces changes politely to screen readers.
This component's root element must remain mounted in the DOM to announce
changes consistently across screen readers. Avoid hiding or removing the
component itself with display: none, hidden, aria-hidden, or conditional
rendering. Prefer updating or conditionally rendering its children instead.
Renders a `` element.

Empty Props:

Prop Type Default Description
className string | ((state: Autocomplete.Empty.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Empty.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Empty.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Empty.Props

Re-export of Empty props.

Empty.State

typescript
type AutocompleteEmptyState = {};

Collection

Renders filtered list items.
Doesn't render its own HTML element.

If rendering a flat list, pass a function child to the List component instead, which implicitly wraps it.

Collection Props:

Prop Type Default Description
children* ((item: any, index: number) => React.ReactNode) - -

Collection.Props

Re-export of Collection props.

Collection.State

typescript
type AutocompleteCollectionState = {};

Row

Displays a single row of items in a grid list.
Enable grid on the root component to turn the listbox into a grid.
Renders a `` element.

Row Props:

Prop Type Default Description
className string | ((state: Autocomplete.Row.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.Row.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.Row.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Row.Props

Re-export of Row props.

Row.State

typescript
type AutocompleteRowState = {};

InputGroup

A wrapper for the input and its associated controls.
Renders a `` element.

InputGroup Props:

Prop Type Default Description
className string | ((state: Autocomplete.InputGroup.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Autocomplete.InputGroup.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Autocomplete.InputGroup.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

InputGroup Data Attributes:

Attribute Type Description
data-popup-open - Present when the corresponding popup is open.
data-popup-side 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null Indicates which side the corresponding popup is positioned relative to its anchor.
data-list-empty - Present when the corresponding items list is empty.
data-pressed - Present when the input group is pressed.
data-disabled - Present when the component is disabled.
data-readonly - Present when the component is readonly.
data-valid - Present when the component is in a valid state (when wrapped in Field.Root).
data-invalid - Present when the component is in an invalid state (when wrapped in Field.Root).
data-dirty - Present when the component's value has changed (when wrapped in Field.Root).
data-touched - Present when the component has been touched (when wrapped in Field.Root).
data-filled - Present when the component has a value (when wrapped in Field.Root).
data-focused - Present when the component is focused (when wrapped in Field.Root).

InputGroup.Props

Re-export of InputGroup props.

InputGroup.State

typescript
type AutocompleteInputGroupState = {
  /** Whether the corresponding popup is open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the component should ignore user edits. */
  readOnly: boolean;
  /** Indicates which side the corresponding popup is positioned relative to its anchor. */
  popupSide: Side | null;
  /** Present when the corresponding items list is empty. */
  listEmpty: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

useFilter

Matches items against a query using Intl.Collator for robust string matching.

Parameters:

Parameter Type Default Description
options? AutocompleteFilterOptions {} -

Return Value:

tsx
type ReturnValue = AutocompleteFilter;

useFilteredItems

Returns the internally filtered items.
Treat the result as read-only: it is internal state and may be a shared frozen array.

Return Value:

tsx
type ReturnValue = T[];

Additional Types

AutocompleteArrowDataAttributes

Data attributes of Arrow.

typescript
declare namespace AutocompleteArrowDataAttributes {
  /** Present when the popup is open. */
  const open: 'data-open';
  /** Present when the popup is closed. */
  const closed: 'data-closed';
  /**
   * Indicates which side the popup is positioned relative to the trigger.
   * @type 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'
   */
  const side: 'data-side';
  /**
   * Indicates how the popup is aligned relative to specified side.
   * @type 'start' | 'center' | 'end'
   */
  const align: 'data-align';
  /** Present when the arrow is uncentered. */
  const uncentered: 'data-uncentered';
}

AutocompleteBackdropDataAttributes

Data attributes of Backdrop.

typescript
declare namespace AutocompleteBackdropDataAttributes {
  /** Present when the popup is open. */
  const open: 'data-open';
  /** Present when the popup is closed. */
  const closed: 'data-closed';
  /** Present when the popup begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the popup is animating out. */
  const endingStyle: 'data-ending-style';
}

AutocompleteClearDataAttributes

Data attributes of Clear.

typescript
declare namespace AutocompleteClearDataAttributes {
  /** Present when the corresponding popup is open. */
  const popupOpen: 'data-popup-open';
  /** Present when the button is disabled. */
  const disabled: 'data-disabled';
  /** Present when the clear button is visible. */
  const visible: 'data-visible';
  /** Present when the button begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the button is animating out. */
  const endingStyle: 'data-ending-style';
}

AutocompleteFilter

typescript
type AutocompleteFilter = {
  /** Returns whether the item matches the query anywhere. */
  contains: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
  /** Returns whether the item starts with the query. */
  startsWith: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
  /** Returns whether the item ends with the query. */
  endsWith: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
};

AutocompleteFilterOptions

typescript
type AutocompleteFilterOptions = {
  /**
   * The locale to use for string comparison.
   * Defaults to the user's runtime locale.
   */
  locale?: Intl.LocalesArgument;
};

AutocompleteInputDataAttributes

Data attributes of Input.

typescript
declare namespace AutocompleteInputDataAttributes {
  /** Present when the corresponding popup is open. */
  const popupOpen: 'data-popup-open';
  /** Present when the input is pressed. */
  const pressed: 'data-pressed';
  /** Present when the component is disabled. */
  const disabled: 'data-disabled';
  /** Present when the component is readonly. */
  const readonly: 'data-readonly';
  /**
   * Indicates which side the corresponding popup is positioned relative to its anchor.
   * @type 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null
   */
  const popupSide: 'data-popup-side';
  /** Present when the component is required. */
  const required: 'data-required';
  /** Present when the component is in a valid state (when wrapped in Field.Root). */
  const valid: 'data-valid';
  /** Present when the component is in an invalid state (when wrapped in Field.Root). */
  const invalid: 'data-invalid';
  /** Present when the component has been touched (when wrapped in Field.Root). */
  const touched: 'data-touched';
  /** Present when the component's value has changed (when wrapped in Field.Root). */
  const dirty: 'data-dirty';
  /** Present when the component has a value (when wrapped in Field.Root). */
  const filled: 'data-filled';
  /** Present when the input is focused (when wrapped in Field.Root). */
  const focused: 'data-focused';
  /** Present when the corresponding items list is empty. */
  const listEmpty: 'data-list-empty';
}

AutocompleteInputGroupDataAttributes

Data attributes of InputGroup.

typescript
declare namespace AutocompleteInputGroupDataAttributes {
  /** Present when the corresponding popup is open. */
  const popupOpen: 'data-popup-open';
  /** Present when the input group is pressed. */
  const pressed: 'data-pressed';
  /** Present when the component is disabled. */
  const disabled: 'data-disabled';
  /** Present when the component is readonly. */
  const readonly: 'data-readonly';
  /**
   * Indicates which side the corresponding popup is positioned relative to its anchor.
   * @type 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null
   */
  const popupSide: 'data-popup-side';
  /** Present when the component is in a valid state (when wrapped in Field.Root). */
  const valid: 'data-valid';
  /** Present when the component is in an invalid state (when wrapped in Field.Root). */
  const invalid: 'data-invalid';
  /** Present when the component has been touched (when wrapped in Field.Root). */
  const touched: 'data-touched';
  /** Present when the component's value has changed (when wrapped in Field.Root). */
  const dirty: 'data-dirty';
  /** Present when the component has a value (when wrapped in Field.Root). */
  const filled: 'data-filled';
  /** Present when the component is focused (when wrapped in Field.Root). */
  const focused: 'data-focused';
  /** Present when the corresponding items list is empty. */
  const listEmpty: 'data-list-empty';
}

AutocompleteItemDataAttributes

Data attributes of Item.

typescript
declare namespace AutocompleteItemDataAttributes {
  /** Present when the item is highlighted. */
  const highlighted: 'data-highlighted';
  /** Present when the item is disabled. */
  const disabled: 'data-disabled';
}

AutocompletePopupDataAttributes

Data attributes of Popup.

typescript
declare namespace AutocompletePopupDataAttributes {
  /** Present when the popup is open. */
  const open: 'data-open';
  /** Present when the popup is closed. */
  const closed: 'data-closed';
  /** Present when the popup begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the popup is animating out. */
  const endingStyle: 'data-ending-style';
  /**
   * Indicates which side the popup is positioned relative to the trigger.
   * @type 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'
   */
  const side: 'data-side';
  /**
   * Indicates how the popup is aligned relative to specified side.
   * @type 'start' | 'center' | 'end'
   */
  const align: 'data-align';
  /** Present when the anchor is hidden. */
  const anchorHidden: 'data-anchor-hidden';
  /** Present when the items list is empty. */
  const empty: 'data-empty';
}

AutocompletePositionerCssVariables

CSS variables of Positioner.

typescript
declare namespace AutocompletePositionerCssVariables {
  /**
   * The available width between the trigger and the edge of the viewport.
   * @type number
   */
  const availableWidth: '--available-width';
  /**
   * The available height between the trigger and the edge of the viewport.
   * @type number
   */
  const availableHeight: '--available-height';
  /**
   * The anchor's width.
   * @type number
   */
  const anchorWidth: '--anchor-width';
  /**
   * The anchor's height.
   * @type number
   */
  const anchorHeight: '--anchor-height';
  /**
   * The coordinates that this element is anchored to. Used for animations and transitions.
   * @type string
   */
  const transformOrigin: '--transform-origin';
}

AutocompletePositionerDataAttributes

Data attributes of Positioner.

typescript
declare namespace AutocompletePositionerDataAttributes {
  /** Present when the popup is open. */
  const open: 'data-open';
  /** Present when the popup is closed. */
  const closed: 'data-closed';
  /** Present when the anchor is hidden. */
  const anchorHidden: 'data-anchor-hidden';
  /**
   * Indicates which side the popup is positioned relative to the trigger.
   * @type 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'
   */
  const side: 'data-side';
  /**
   * Indicates how the popup is aligned relative to specified side.
   * @type 'start' | 'center' | 'end'
   */
  const align: 'data-align';
  /** Present when the items list is empty. */
  const empty: 'data-empty';
}

AutocompleteSeparatorDataAttributes

Data attributes of Separator.

typescript
declare namespace AutocompleteSeparatorDataAttributes {
  /**
   * Indicates the orientation of the separator.
   * @type 'horizontal' | 'vertical'
   */
  const orientation: 'data-orientation';
}

AutocompleteTriggerDataAttributes

Data attributes of Trigger.

text
/* Detailed source-code truncated for AI context efficiency. */

External Types

Side

typescript
type Side = 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';

Align

typescript
type Align = 'start' | 'center' | 'end';

OffsetFunction

typescript
type OffsetFunction = (data: {
  side: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
  align: 'start' | 'center' | 'end';
  anchor: { width: number; height: number };
  positioner: { width: number; height: number };
}) => number;

InteractionType

typescript
type InteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard' | '';

Orientation

typescript
type Orientation = 'horizontal' | 'vertical';

Export Groups

  • Autocomplete.Root: Autocomplete.Root, Autocomplete.Root.Props, Autocomplete.Root.State, Autocomplete.Root.Actions, Autocomplete.Root.ChangeEventReason, Autocomplete.Root.ChangeEventDetails, Autocomplete.Root.OpenChangeEventDetails, Autocomplete.Root.HighlightEventReason, Autocomplete.Root.HighlightEventDetails
  • Autocomplete.Value: Autocomplete.Value, Autocomplete.Value.State, Autocomplete.Value.Props
  • Autocomplete.Trigger: Autocomplete.Trigger, Autocomplete.Trigger.State, Autocomplete.Trigger.Props
  • Autocomplete.Input: Autocomplete.Input, Autocomplete.Input.State, Autocomplete.Input.Props
  • Autocomplete.InputGroup: Autocomplete.InputGroup, Autocomplete.InputGroup.State, Autocomplete.InputGroup.Props
  • Autocomplete.Icon: Autocomplete.Icon, Autocomplete.Icon.State, Autocomplete.Icon.Props
  • Autocomplete.Clear: Autocomplete.Clear, Autocomplete.Clear.State, Autocomplete.Clear.Props
  • Autocomplete.List: Autocomplete.List, Autocomplete.List.State, Autocomplete.List.Props
  • Autocomplete.Status: Autocomplete.Status, Autocomplete.Status.State, Autocomplete.Status.Props
  • Autocomplete.Portal: Autocomplete.Portal, Autocomplete.Portal.State, Autocomplete.Portal.Props
  • Autocomplete.Backdrop: Autocomplete.Backdrop, Autocomplete.Backdrop.Props, Autocomplete.Backdrop.State
  • Autocomplete.Positioner: Autocomplete.Positioner, Autocomplete.Positioner.State, Autocomplete.Positioner.Props
  • Autocomplete.Popup: Autocomplete.Popup, Autocomplete.Popup.State, Autocomplete.Popup.Props
  • Autocomplete.Arrow: Autocomplete.Arrow, Autocomplete.Arrow.State, Autocomplete.Arrow.Props
  • Autocomplete.Group: Autocomplete.Group, Autocomplete.Group.State, Autocomplete.Group.Props
  • Autocomplete.GroupLabel: Autocomplete.GroupLabel, Autocomplete.GroupLabel.State, Autocomplete.GroupLabel.Props
  • Autocomplete.Item: Autocomplete.Item, Autocomplete.Item.State, Autocomplete.Item.Props
  • Autocomplete.Row: Autocomplete.Row, Autocomplete.Row.State, Autocomplete.Row.Props
  • Autocomplete.Collection: Autocomplete.Collection, Autocomplete.Collection.State, Autocomplete.Collection.Props
  • Autocomplete.Empty: Autocomplete.Empty, Autocomplete.Empty.State, Autocomplete.Empty.Props
  • Autocomplete.Separator: Autocomplete.Separator, Autocomplete.Separator.Props, Autocomplete.Separator.State
  • Autocomplete.useFilter
  • Autocomplete.useFilteredItems
  • Default: AutocompleteSeparatorProps, AutocompleteSeparatorState, AutocompleteInputProps, AutocompleteInputState, AutocompleteIconProps, AutocompleteIconState, AutocompleteClearProps, AutocompleteClearState, AutocompletePopupProps, AutocompletePopupState, AutocompletePositionerProps, AutocompletePositionerState, AutocompleteListProps, AutocompleteListState, AutocompleteRowProps, AutocompleteRowState, AutocompleteArrowProps, AutocompleteArrowState, AutocompleteBackdropProps, AutocompleteBackdropState, AutocompletePortalProps, AutocompletePortalState, AutocompleteGroupProps, AutocompleteGroupState, AutocompleteGroupLabelProps, AutocompleteGroupLabelState, AutocompleteEmptyProps, AutocompleteEmptyState, AutocompleteStatusProps, AutocompleteStatusState, AutocompleteCollectionState, AutocompleteCollectionProps, AutocompleteFilter, AutocompleteFilterOptions, AutocompleteTriggerDataAttributes, AutocompleteInputDataAttributes, AutocompleteInputGroupDataAttributes, AutocompleteClearDataAttributes, AutocompleteBackdropDataAttributes, AutocompletePositionerCssVariables, AutocompletePositionerDataAttributes, AutocompletePopupDataAttributes, AutocompleteArrowDataAttributes, AutocompleteItemDataAttributes, AutocompleteSeparatorDataAttributes, AutocompleteRootState, AutocompleteRootActions, AutocompleteRootChangeEventReason, AutocompleteRootChangeEventDetails, AutocompleteRootOpenChangeEventDetails, AutocompleteRootHighlightEventReason, AutocompleteRootHighlightEventDetails, AutocompleteRootProps, AutocompleteTriggerState, AutocompleteTriggerProps, AutocompleteInputGroupState, AutocompleteInputGroupProps, AutocompleteItemState, AutocompleteItemProps, AutocompleteValueState, AutocompleteValueProps

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

  • Autocomplete.Root.Props: AutocompleteRootProps
  • Autocomplete.Root.State: AutocompleteRootState
  • Autocomplete.Root.Actions: AutocompleteRootActions
  • Autocomplete.Root.ChangeEventReason: AutocompleteRootChangeEventReason
  • Autocomplete.Root.ChangeEventDetails: AutocompleteRootChangeEventDetails
  • Autocomplete.Root.OpenChangeEventDetails: AutocompleteRootOpenChangeEventDetails
  • Autocomplete.Root.HighlightEventReason: AutocompleteRootHighlightEventReason
  • Autocomplete.Root.HighlightEventDetails: AutocompleteRootHighlightEventDetails
  • Autocomplete.Value.State: AutocompleteValueState
  • Autocomplete.Value.Props: AutocompleteValueProps
  • Autocomplete.Trigger.State: AutocompleteTriggerState
  • Autocomplete.Trigger.Props: AutocompleteTriggerProps
  • Autocomplete.Input.State: AutocompleteInputState
  • Autocomplete.Input.Props: AutocompleteInputProps
  • Autocomplete.InputGroup.State: AutocompleteInputGroupState
  • Autocomplete.InputGroup.Props: AutocompleteInputGroupProps
  • Autocomplete.Icon.State: AutocompleteIconState
  • Autocomplete.Icon.Props: AutocompleteIconProps
  • Autocomplete.Clear.State: AutocompleteClearState
  • Autocomplete.Clear.Props: AutocompleteClearProps
  • Autocomplete.List.State: AutocompleteListState
  • Autocomplete.List.Props: AutocompleteListProps
  • Autocomplete.Status.State: AutocompleteStatusState
  • Autocomplete.Status.Props: AutocompleteStatusProps
  • Autocomplete.Portal.State: AutocompletePortalState
  • Autocomplete.Portal.Props: AutocompletePortalProps
  • Autocomplete.Backdrop.Props: AutocompleteBackdropProps
  • Autocomplete.Backdrop.State: AutocompleteBackdropState
  • Autocomplete.Positioner.State: AutocompletePositionerState
  • Autocomplete.Positioner.Props: AutocompletePositionerProps
  • Autocomplete.Popup.State: AutocompletePopupState
  • Autocomplete.Popup.Props: AutocompletePopupProps
  • Autocomplete.Arrow.State: AutocompleteArrowState
  • Autocomplete.Arrow.Props: AutocompleteArrowProps
  • Autocomplete.Group.State: AutocompleteGroupState
  • Autocomplete.Group.Props: AutocompleteGroupProps
  • Autocomplete.GroupLabel.State: AutocompleteGroupLabelState
  • Autocomplete.GroupLabel.Props: AutocompleteGroupLabelProps
  • Autocomplete.Item.State: AutocompleteItemState
  • Autocomplete.Item.Props: AutocompleteItemProps
  • Autocomplete.Row.State: AutocompleteRowState
  • Autocomplete.Row.Props: AutocompleteRowProps
  • Autocomplete.Collection.State: AutocompleteCollectionState
  • Autocomplete.Collection.Props: AutocompleteCollectionProps
  • Autocomplete.Empty.State: AutocompleteEmptyState
  • Autocomplete.Empty.Props: AutocompleteEmptyProps
  • Autocomplete.Separator.Props: AutocompleteSeparatorProps
  • Autocomplete.Separator.State: AutocompleteSeparatorState

Src App (Docs) React Components Avatar Page (`docs/src/app/(docs)/react/components/avatar/page.mdx`)

Avatar

An easily stylable avatar component.

import { DemoAvatarHero } from './demos/hero';

Anatomy

Import the component and assemble its parts:

jsx title="anatomy"
import { Avatar } from '@base-ui/react/avatar';

<Avatar.Root>
  <Avatar.Image src="" />
  <Avatar.Fallback>LT</Avatar.Fallback>
</Avatar.Root>;

Optimized and lazy-loaded images

By default, <Avatar.Image> preloads src and renders the image only once it has loaded. This doesn't compose with image optimizers such as next/image, which serve a different URL than the raw src, or with loading="lazy".

Add the keepMounted prop to render the image element right away and let it load in place. Only the image that is actually displayed is requested:

jsx title="using next/image"
import Image from 'next/image';

<Avatar.Root>
  <Avatar.Fallback>LT</Avatar.Fallback>
  <Avatar.Image keepMounted render={<Image src="/avatar.png" width={32} height={32} alt="" />} />
</Avatar.Root>;

Stacking

With keepMounted, the image and the fallback are both present until the image loads. The image is hidden from assistive technology until then, so the fallback provides the accessible name on its own.

Stack the two in the same box, and place <Avatar.Image> after <Avatar.Fallback>. Both are positioned, so whichever comes later in the DOM paints on top. The fallback then shows through until the image covers it.

A loading image paints nothing, so the fallback shows through on its own. An image that failed to load paints a broken-image icon on top of it. Hide the image in either state with the data-loading and data-error attributes:

css title="stacked image and fallback"
.Root {
  position: relative;
}

.Image,
.Fallback {
  position: absolute;
  inset: 0;
}

.Image[data-loading],
.Image[data-error] {
  visibility: hidden;
}

Avoid display: none here: an element without a box never intersects the viewport, so loading="lazy" would never fetch the image. visibility and opacity both keep lazy loading working.

Server rendering

With keepMounted, the image is part of the server-rendered HTML and starts loading before hydration. So is the fallback, which stays visible until hydration resolves the loading status. A cached image is displayed immediately, without an enter animation.

API reference

import { TypesAvatar, TypesAvatarAdditional } from './types';

Root

<TypesAvatar.Root />

Image

<TypesAvatar.Image />

Fallback

<TypesAvatar.Fallback />

Additional types

<TypesAvatarAdditional showAdditionalTypes={['imageloadingstatus']} />

export const metadata = {
keywords: [
'React Avatar',
'Avatar Component',
'Profile Image UI',
'User Image',
'User Avatar',
'Profile Picture',
'Account Image',
'Profile Icon',
'Initials Fallback',
'Accessible Avatar',
'Headless React Components',
'Customizable Avatar',
'Base UI',
],
};

Src App (Docs) React Components Avatar Types (`docs/src/app/(docs)/react/components/avatar/types.md`)

Avatar

API Reference

Root

Displays a user's profile picture, initials, or fallback icon.
Renders a `` element.

Root Props:

Prop Type Default Description
className string | ((state: Avatar.Root.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Avatar.Root.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Avatar.Root.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Root.Props

Re-export of Root props.

Root.State

typescript
type AvatarRootState = {
  /** The image loading status. */
  imageLoadingStatus: ImageLoadingStatus;
};

Image

The image to be displayed in the avatar.
Renders an `` element.

Image Props:

Prop Type Default Description
onLoadingStatusChange ((status: ImageLoadingStatus) => void) - Callback fired when the loading status changes.
className string | ((state: Avatar.Image.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Avatar.Image.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted boolean false Whether the image element stays mounted and loads in place instead of being preloaded. Supports loading="lazy" and optimized image components such as next/image.
render ReactElement | ((props: React.DetailedHTMLProps<React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, state: Avatar.Image.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Image Data Attributes:

Attribute Type Description
data-error - Present when the image failed to load.
data-loading - Present while the image is loading.
data-starting-style - Present when the image begins animating in.
data-ending-style - Present when the image is animating out.

Image.Props

Re-export of Image props.

Image.State

typescript
type AvatarImageState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** The image loading status. */
  imageLoadingStatus: ImageLoadingStatus;
};

Fallback

Rendered when the image fails to load or when no image is provided.
Renders a `` element.

Fallback Props:

Prop Type Default Description
delay number 0 How long to wait before showing the fallback. Specified in milliseconds.
className string | ((state: Avatar.Fallback.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Avatar.Fallback.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Avatar.Fallback.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Fallback.Props

Re-export of Fallback props.

Fallback.State

typescript
type AvatarFallbackState = {
  /** The image loading status. */
  imageLoadingStatus: ImageLoadingStatus;
};

Additional Types

AvatarImageDataAttributes

Data attributes of Image.

typescript
declare namespace AvatarImageDataAttributes {
  /** Present while the image is loading. */
  const loading: 'data-loading';
  /** Present when the image failed to load. */
  const error: 'data-error';
  /** Present when the image begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the image is animating out. */
  const endingStyle: 'data-ending-style';
}

ImageLoadingStatus

typescript
type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';

Export Groups

  • Avatar.Root: Avatar.Root, Avatar.Root.State, Avatar.Root.Props
  • Avatar.Image: Avatar.Image, Avatar.Image.State, Avatar.Image.Props
  • Avatar.Fallback: Avatar.Fallback, Avatar.Fallback.State, Avatar.Fallback.Props
  • Default: AvatarImageDataAttributes, ImageLoadingStatus, AvatarRootState, AvatarRootProps, AvatarImageState, AvatarImageProps, AvatarFallbackState, AvatarFallbackProps

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

  • Avatar.Root.State: AvatarRootState
  • Avatar.Root.Props: AvatarRootProps
  • Avatar.Image.State: AvatarImageState
  • Avatar.Image.Props: AvatarImageProps
  • Avatar.Fallback.State: AvatarFallbackState
  • Avatar.Fallback.Props: AvatarFallbackProps

Src App (Docs) React Components Button Page (`docs/src/app/(docs)/react/components/button/page.mdx`)

Button

A button component that can be rendered as another tag or focusable when disabled.

import { DemoButtonHero } from './demos/hero';

Usage guidelines

  • Submit buttons: Unlike the native button element, type="submit" must be specified on Button for it to act as a submit button.
  • Links: The Button component enforces button semantics (role="button", keyboard interaction, disabled state). It should not be used for links. See Rendering links as buttons below.

Anatomy

Import the component:

jsx title="anatomy"
import { Button } from '@base-ui/react/button';

<Button />;

Examples

Rendering as another tag

The button can remain keyboard accessible while being rendered as another tag, such as a ``, by specifying nativeButton={false}.

jsx title="custom tag button"
import { Button } from '@base-ui/react/button';

// @highlight-text "nativeButton={false}"
<Button render={<div />} nativeButton={false}>
  Button that can contain complex children
</Button>;

The Button component enforces button semantics. nativeButton={false} signals that the rendered tag is not a ``, but it must still be a tag that can receive button semantics (role="button", keyboard interaction handlers). Links (<a>) have their own semantics and should not be rendered as buttons through the render prop.

If a link needs to look like a button visually, style the <a> element directly with CSS rather than using the Button component.

Loading states

For buttons that enter a loading state after activation, specify focusableWhenDisabled so focus remains on the button while it is disabled. Because some browser and screen reader combinations do not reliably announce changes to a focused button's descendant text, use aria-labelledby to make the changing text the button's explicit accessible name.

import { DemoButtonLoading } from './demos/loading';

API reference

import { TypesButton } from './types';

export const metadata = {
keywords: [
'React Button',
'Button Component',
'Focusable Disabled Button',
'Custom Element Button',
'Clickable Element',
'Action Button',
'Submit Button',
'Accessible Button',
'Loading State Button',
'Button as Link',
'Link Button',
'Headless React Components',
'Base UI',
],
};

Src App (Docs) React Components Button Types (`docs/src/app/(docs)/react/components/button/types.md`)

Button

API Reference

Button

A button component that can be used to trigger actions.
Renders a `` element.

Button Props:

Prop Type Default Description
focusableWhenDisabled boolean false Whether the button should be focusable when disabled.
nativeButton boolean true Whether the component renders a native element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example,).
className string | ((state: Button.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Button.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Button.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Button Data Attributes:

Attribute Type Description
data-disabled - Present when the button is disabled.

Button.Props

Re-export of Button props.

Button.State

typescript
type ButtonState = {
  /** Whether the button should ignore user interaction. */
  disabled: boolean;
};

Additional Types

ButtonDataAttributes

Data attributes of Button.

typescript
declare namespace ButtonDataAttributes {
  /** Present when the button is disabled. */
  const disabled: 'data-disabled';
}

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

  • Button.State: ButtonState
  • Button.Props: ButtonProps

Src App (Docs) React Components Checkbox Group Page (`docs/src/app/(docs)/react/components/checkbox-group/page.mdx`)

Checkbox Group

Provides shared state to a series of checkboxes.

import { DemoCheckboxGroupHero } from './demos/hero';

Usage guidelines

Anatomy

Checkbox Group is composed together with Checkbox. Import the components and place them together:

jsx title="anatomy"
import { Checkbox } from '@base-ui/react/checkbox';
import { CheckboxGroup } from '@base-ui/react/checkbox-group';

<CheckboxGroup>
  <Checkbox.Root />
</CheckboxGroup>;

Examples

Labeling a checkbox group

Label the group with aria-labelledby and a sibling label element:

tsx title="using aria-labelledby to label a checkbox group"
<div id="protocols-label">Allowed network protocols</div>
<CheckboxGroup aria-labelledby="protocols-label">{/* ... */}</CheckboxGroup>

An enclosing <label> is the simplest labeling pattern for each checkbox:

tsx title="using an enclosing label to label a checkbox"
// @highlight
<label>
  <Checkbox.Root value="http" />
  HTTP
  {/* @highlight */}
</label>

Rendering as a native button

By default, <Checkbox.Root> renders a `` element to support enclosing labels. Prefer rendering each checkbox as a native button when using sibling labels (htmlFor/id).

tsx title="sibling label pattern with a native button"
<div id="protocols-label">Allowed network protocols</div>
<CheckboxGroup aria-labelledby="protocols-label">
  <div>
    <label htmlFor="protocol-http">HTTP</label>
    {/* @highlight-text "nativeButton" "render={<button />}" */}
    <Checkbox.Root id="protocol-http" value="http" nativeButton render={<button />}>
      <Checkbox.Indicator />
    </Checkbox.Root>
  </div>
</CheckboxGroup>

Native buttons with wrapping labels are supported by using the render callback to avoid invalid HTML, so the hidden input is placed outside the label:

tsx title="render callback"
<div id="protocols-label">Allowed network protocols</div>
<CheckboxGroup aria-labelledby="protocols-label">
  <Checkbox.Root
    value="http"
    nativeButton
    // @highlight-start
    render={(buttonProps) => (
      <label>
        <button {...buttonProps} />
        HTTP
      </label>
    )}
    {/* @highlight-end */}
  />
</CheckboxGroup>

Form integration

Use Field and Fieldset for group labeling and form integration:

tsx title="using checkbox group in a form"
<Form>
  {/* @highlight */}
  <Field.Root name="allowedNetworkProtocols">
    <Fieldset.Root render={<CheckboxGroup />}>
      <Fieldset.Legend>Allowed network protocols</Fieldset.Legend>
      <Field.Item>
        <Field.Label>
          <Checkbox.Root value="http" />
          HTTP
        </Field.Label>
      </Field.Item>
      <Field.Item>
        <Field.Label>
          <Checkbox.Root value="https" />
          HTTPS
        </Field.Label>
      </Field.Item>
      <Field.Item>
        <Field.Label>
          <Checkbox.Root value="ssh" />
          SSH
        </Field.Label>
      </Field.Item>
    </Fieldset.Root>
  </Field.Root>
</Form>

Parent checkbox

A checkbox that controls other checkboxes within a <CheckboxGroup> can be created:

  1. Make <CheckboxGroup> a controlled component
  2. Pass an array of all the child checkbox values to the allValues prop on the <CheckboxGroup> component
  3. Add the parent boolean prop to the parent <Checkbox.Root>

The group controls the parent checkbox's indeterminate state when some, but not all, child checkboxes are checked.

import { DemoCheckboxGroupParent } from './demos/parent';

Nested parent checkbox

import { DemoCheckboxGroupNested } from './demos/nested';

API reference

import { TypesCheckboxGroup } from './types';

export const metadata = {
keywords: [
'React Checkbox Group',
'Checkbox Group Component',
'Grouped Checkboxes',
'Multiple Selection',
'Checkbox List',
'Multi-Select Checkboxes',
'Parent Child Checkbox',
'Accessible Checkbox Group',
'Form Fieldset Control',
'Headless React Components',
'Base UI',
],
};

Src App (Docs) React Components Checkbox Group Types (`docs/src/app/(docs)/react/components/checkbox-group/types.md`)

Checkbox Group

API Reference

CheckboxGroup

Provides a shared state to a series of checkboxes.

CheckboxGroup Props:

Prop Type Default Description
defaultValue string[] - Names of the checkboxes in the group that should be initially ticked. To render a controlled checkbox group, use the value prop instead.
value string[] - Names of the checkboxes in the group that should be ticked. To render an uncontrolled checkbox group, use the defaultValue prop instead.
onValueChange ((value: string[], eventDetails: CheckboxGroup.ChangeEventDetails) => void) - Event handler called when a checkbox in the group is ticked or unticked. Provides the new value as an argument.
allValues string[] - Names of all checkboxes in the group. Use this when creating a parent checkbox.
disabled boolean false Whether the component should ignore user interaction.
className string | ((state: CheckboxGroup.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: CheckboxGroup.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: CheckboxGroup.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

CheckboxGroup Data Attributes:

Attribute Type Description
data-disabled - Present when the checkbox group is disabled.

CheckboxGroup.Props

Re-export of CheckboxGroup props.

CheckboxGroup.State

typescript
type CheckboxGroupState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

CheckboxGroup.ChangeEventReason

typescript
type CheckboxGroupChangeEventReason = 'none';

CheckboxGroup.ChangeEventDetails

typescript
type CheckboxGroupChangeEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};

Additional Types

CheckboxGroupDataAttributes

Data attributes of CheckboxGroup.

typescript
declare namespace CheckboxGroupDataAttributes {
  /** Present when the checkbox group is disabled. */
  const disabled: 'data-disabled';
}

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

  • CheckboxGroup.State: CheckboxGroupState
  • CheckboxGroup.Props: CheckboxGroupProps
  • CheckboxGroup.ChangeEventReason: CheckboxGroupChangeEventReason
  • CheckboxGroup.ChangeEventDetails: CheckboxGroupChangeEventDetails

Src App (Docs) React Components Checkbox Page (`docs/src/app/(docs)/react/components/checkbox/page.mdx`)

Checkbox

An easily stylable checkbox component.

import { DemoCheckboxBasic } from './demos/hero';

Usage guidelines

  • Form controls must have an accessible name: It can be created using a <label> element or the Field component. See Labeling a checkbox and the forms guide.

Anatomy

Import the component and assemble its parts:

jsx title="anatomy"
import { Checkbox } from '@base-ui/react/checkbox';

<Checkbox.Root>
  <Checkbox.Indicator />
</Checkbox.Root>;

Examples

Labeling a checkbox

An enclosing <label> is the simplest labeling pattern:

tsx title="wrapping a label around a checkbox"
// @highlight
<label>
  <Checkbox.Root />
  Accept terms and conditions
  {/* @highlight */}
</label>

Rendering as a native button

By default, <Checkbox.Root> renders a `` element to support enclosing labels. Prefer rendering the checkbox as a native button when using sibling labels (htmlFor/id).

tsx title="sibling label pattern with a native button"
<div>
  <label htmlFor="notifications-checkbox">Enable notifications</label>
  {/* @highlight-text "nativeButton" "render={<button />}" */}
  <Checkbox.Root id="notifications-checkbox" nativeButton render={<button />}>
    <Checkbox.Indicator />
  </Checkbox.Root>
</div>

Native buttons with wrapping labels are supported by using the render callback to avoid invalid HTML, so the hidden input is placed outside the label:

tsx title="render callback"
<Checkbox.Root
  nativeButton
  // @highlight-start
  render={(buttonProps) => (
    <label>
      <button {...buttonProps} />
      Enable notifications
    </label>
  )}
  {/* @highlight-end */}
/>

Form integration

Use Field to handle label associations and form integration:

tsx title="using checkbox in a form"
<Form>
  {/* @highlight */}
  <Field.Root name="stayLoggedIn">
    <Field.Label>
      <Checkbox.Root />
      Stay logged in for 7 days
    </Field.Label>
  </Field.Root>
</Form>

API reference

import { TypesCheckbox } from './types';

Root

<TypesCheckbox.Root />

Indicator

<TypesCheckbox.Indicator />

export const metadata = {
keywords: [
'React Checkbox',
'Checkbox Component',
'Accessible Checkbox',
'Customizable Checkbox',
'Form Control Checkbox',
'Checkmark',
'Tick Box',
'Selection Control',
'Checkbox Input',
'Binary Input',
'Checked State',
'Indeterminate Checkbox',
'Tri-State Checkbox',
'Headless React Components',
'Input Indicator',
'Base UI',
],
};

Src App (Docs) React Components Checkbox Types (`docs/src/app/(docs)/react/components/checkbox/types.md`)

Checkbox

API Reference

Root

Represents the checkbox itself.
Renders a element and a hidden beside.

Root Props:

Prop Type Default Description
name string undefined Identifies the field when a form is submitted.
defaultChecked boolean false Whether the checkbox is initially ticked. To render a controlled checkbox, use the checked prop instead.
checked boolean undefined Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the defaultChecked prop instead.
onCheckedChange ((checked: boolean, eventDetails: Checkbox.Root.ChangeEventDetails) => void) - Event handler called when the checkbox is ticked or unticked.
indeterminate boolean false Whether the checkbox is in a mixed state: neither ticked, nor unticked.
value string - The checkbox's value. Identifies it within a Checkbox Group, falling back to name when omitted. When submitting a form, a checked box submits value; with no value, it submits the native "on".
form string - Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
nativeButton boolean false Whether the component renders a native `` element when replacing it via the render prop. Set to true if the rendered element is a native button.
parent boolean false Whether the checkbox controls a group of child checkboxes. Must be used in a Checkbox Group.
uncheckedValue string - The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
disabled boolean false Whether the component should ignore user interaction.
readOnly boolean false Whether the user should be unable to tick or untick the checkbox.
required boolean false Whether the user must tick the checkbox before submitting a form.
inputRef React.Ref<HTMLInputElement> - A ref to access the hidden `` element.
id string - The id of the input element.
className string | ((state: Checkbox.Root.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Checkbox.Root.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Checkbox.Root.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Root Data Attributes:

Attribute Type Description
data-checked - Present when the checkbox is checked.
data-unchecked - Present when the checkbox is not checked.
data-disabled - Present when the checkbox is disabled.
data-readonly - Present when the checkbox is readonly.
data-required - Present when the checkbox is required.
data-valid - Present when the checkbox is in a valid state (when wrapped in Field.Root).
data-invalid - Present when the checkbox is in an invalid state (when wrapped in Field.Root).
data-dirty - Present when the checkbox's value has changed (when wrapped in Field.Root).
data-touched - Present when the checkbox has been touched (when wrapped in Field.Root).
data-filled - Present when the checkbox is checked (when wrapped in Field.Root).
data-focused - Present when the checkbox is focused (when wrapped in Field.Root).
data-indeterminate - Present when the checkbox is in an indeterminate state.

Root.Props

Re-export of Root props.

Root.State

typescript
type CheckboxRootState = {
  /** Whether the checkbox is currently ticked. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to tick or untick the checkbox. */
  readOnly: boolean;
  /** Whether the user must tick the checkbox before submitting a form. */
  required: boolean;
  /** Whether the checkbox is in a mixed state: neither ticked, nor unticked. */
  indeterminate: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Root.ChangeEventReason

typescript
type CheckboxRootChangeEventReason = 'none';

Root.ChangeEventDetails

typescript
type CheckboxRootChangeEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};

Indicator

Indicates whether the checkbox is ticked.
Renders a `` element.

Indicator Props:

Prop Type Default Description
className string | ((state: Checkbox.Indicator.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Checkbox.Indicator.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted boolean false Whether to keep the element in the DOM when the checkbox is not checked.
render ReactElement | ((props: HTMLProps, state: Checkbox.Indicator.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Indicator Data Attributes:

Attribute Type Description
data-checked - Present when the checkbox is checked.
data-unchecked - Present when the checkbox is not checked.
data-disabled - Present when the checkbox is disabled.
data-readonly - Present when the checkbox is readonly.
data-required - Present when the checkbox is required.
data-valid - Present when the checkbox is in a valid state (when wrapped in Field.Root).
data-invalid - Present when the checkbox is in an invalid state (when wrapped in Field.Root).
data-dirty - Present when the checkbox's value has changed (when wrapped in Field.Root).
data-touched - Present when the checkbox has been touched (when wrapped in Field.Root).
data-filled - Present when the checkbox is checked (when wrapped in Field.Root).
data-focused - Present when the checkbox is focused (when wrapped in Field.Root).
data-indeterminate - Present when the checkbox is in an indeterminate state.
data-starting-style - Present when the checkbox indicator begins animating in.
data-ending-style - Present when the checkbox indicator is animating out.

Indicator.Props

Re-export of Indicator props.

Indicator.State

typescript
type CheckboxIndicatorState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the checkbox is currently ticked. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to tick or untick the checkbox. */
  readOnly: boolean;
  /** Whether the user must tick the checkbox before submitting a form. */
  required: boolean;
  /** Whether the checkbox is in a mixed state: neither ticked, nor unticked. */
  indeterminate: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Additional Types

CheckboxIndicatorDataAttributes

Data attributes of Indicator.

typescript
declare namespace CheckboxIndicatorDataAttributes {
  /** Present when the checkbox is checked. */
  const checked: 'data-checked';
  /** Present when the checkbox is not checked. */
  const unchecked: 'data-unchecked';
  /** Present when the checkbox is in an indeterminate state. */
  const indeterminate: 'data-indeterminate';
  /** Present when the checkbox is disabled. */
  const disabled: 'data-disabled';
  /** Present when the checkbox is readonly. */
  const readonly: 'data-readonly';
  /** Present when the checkbox is required. */
  const required: 'data-required';
  /** Present when the checkbox indicator begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the checkbox indicator is animating out. */
  const endingStyle: 'data-ending-style';
  /** Present when the checkbox is in a valid state (when wrapped in Field.Root). */
  const valid: 'data-valid';
  /** Present when the checkbox is in an invalid state (when wrapped in Field.Root). */
  const invalid: 'data-invalid';
  /** Present when the checkbox has been touched (when wrapped in Field.Root). */
  const touched: 'data-touched';
  /** Present when the checkbox's value has changed (when wrapped in Field.Root). */
  const dirty: 'data-dirty';
  /** Present when the checkbox is checked (when wrapped in Field.Root). */
  const filled: 'data-filled';
  /** Present when the checkbox is focused (when wrapped in Field.Root). */
  const focused: 'data-focused';
}

CheckboxRootDataAttributes

Data attributes of Root.

typescript
declare namespace CheckboxRootDataAttributes {
  /** Present when the checkbox is checked. */
  const checked: 'data-checked';
  /** Present when the checkbox is not checked. */
  const unchecked: 'data-unchecked';
  /** Present when the checkbox is in an indeterminate state. */
  const indeterminate: 'data-indeterminate';
  /** Present when the checkbox is disabled. */
  const disabled: 'data-disabled';
  /** Present when the checkbox is readonly. */
  const readonly: 'data-readonly';
  /** Present when the checkbox is required. */
  const required: 'data-required';
  /** Present when the checkbox is in a valid state (when wrapped in Field.Root). */
  const valid: 'data-valid';
  /** Present when the checkbox is in an invalid state (when wrapped in Field.Root). */
  const invalid: 'data-invalid';
  /** Present when the checkbox has been touched (when wrapped in Field.Root). */
  const touched: 'data-touched';
  /** Present when the checkbox's value has changed (when wrapped in Field.Root). */
  const dirty: 'data-dirty';
  /** Present when the checkbox is checked (when wrapped in Field.Root). */
  const filled: 'data-filled';
  /** Present when the checkbox is focused (when wrapped in Field.Root). */
  const focused: 'data-focused';
}

Export Groups

  • Checkbox.Root: Checkbox.Root, Checkbox.Root.State, Checkbox.Root.Props, Checkbox.Root.ChangeEventReason, Checkbox.Root.ChangeEventDetails
  • Checkbox.Indicator: Checkbox.Indicator, Checkbox.Indicator.State, Checkbox.Indicator.Props
  • Default: CheckboxRootDataAttributes, CheckboxIndicatorDataAttributes, CheckboxRootState, CheckboxRootProps, CheckboxRootChangeEventReason, CheckboxRootChangeEventDetails, CheckboxIndicatorState, CheckboxIndicatorProps

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

  • Checkbox.Root.State: CheckboxRootState
  • Checkbox.Root.Props: CheckboxRootProps
  • Checkbox.Root.ChangeEventReason: CheckboxRootChangeEventReason
  • Checkbox.Root.ChangeEventDetails: CheckboxRootChangeEventDetails
  • Checkbox.Indicator.State: CheckboxIndicatorState
  • Checkbox.Indicator.Props: CheckboxIndicatorProps

Src App (Docs) React Components Collapsible Page (`docs/src/app/(docs)/react/components/collapsible/page.mdx`)

Collapsible

A collapsible panel controlled by a button.

import { DemoCollapsibleHero } from './demos/hero';

Anatomy

Import the component and assemble its parts:

jsx title="anatomy"
import { Collapsible } from '@base-ui/react/collapsible';

<Collapsible.Root>
  <Collapsible.Trigger />
  <Collapsible.Panel />
</Collapsible.Root>;

Examples

Hidden until found

The hiddenUntilFound prop hides the closed panel with hidden="until-found" so the browser can search its contents with find-in-page—Ctrl+F (Cmd+F on macOS)—and reveal the panel when a match is found. The closed panel always remains mounted in the DOM, which also makes its contents indexable by search engines.

Older browsers that don't support hidden="until-found" keep the panel hidden until its trigger opens it, and find-in-page skips over the contents.

tsx title="searchable hidden panel"

See the Accordion example for an interactive demo.

API reference

import { TypesCollapsible } from './types';

Root

<TypesCollapsible.Root />

Trigger

<TypesCollapsible.Trigger />

Panel

<TypesCollapsible.Panel />

export const metadata = {
keywords: [
'React Collapsible',
'Collapsible Component',
'Expandable Panel',
'Toggle Panel Button',
'Disclosure Widget',
'Show/Hide Content',
'Accordion Item',
'Accessible Disclosure',
'Headless React Components',
'Collapsible Trigger Panel',
'Base UI',
],
};

Src App (Docs) React Components Collapsible Types (`docs/src/app/(docs)/react/components/collapsible/types.md`)

Collapsible

API Reference

Root

Groups all parts of the collapsible.
Renders a `` element.

Root Props:

Prop Type Default Description
defaultOpen boolean false Whether the collapsible panel is initially open. To render a controlled collapsible, use the open prop instead.
open boolean - Whether the collapsible panel is currently open. To render an uncontrolled collapsible, use the defaultOpen prop instead.
onOpenChange ((open: boolean, eventDetails: Collapsible.Root.ChangeEventDetails) => void) - Event handler called when the panel is opened or closed.
disabled boolean false Whether the component should ignore user interaction.
className string | ((state: Collapsible.Root.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Collapsible.Root.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Collapsible.Root.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Root Data Attributes:

Attribute Type Description
data-open - Present when the collapsible is open.
data-closed - Present when the collapsible is closed.
data-starting-style - Present when the collapsible begins animating in.
data-ending-style - Present when the collapsible is animating out.

Root.Props

Re-export of Root props.

Root.State

typescript
type CollapsibleRootState = {
  /** Whether the collapsible panel is currently open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  transitionStatus: TransitionStatus;
};

Root.ChangeEventReason

typescript
type CollapsibleRootChangeEventReason = 'trigger-press' | 'none';

Root.ChangeEventDetails

typescript
type CollapsibleRootChangeEventDetails = (
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'none'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};

Trigger

A button that opens and closes the collapsible panel.
Renders a `` element.

Trigger Props:

Prop Type Default Description
nativeButton boolean true Whether the component renders a native element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example,).
className string | ((state: Collapsible.Trigger.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Collapsible.Trigger.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Collapsible.Trigger.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Trigger Data Attributes:

Attribute Type Description
data-panel-open - Present when the collapsible panel is open.

Trigger.Props

Re-export of Trigger props.

Trigger.State

typescript
type CollapsibleTriggerState = {
  /** Whether the collapsible panel is currently open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  transitionStatus: TransitionStatus;
};

Panel

A panel with the collapsible contents.
Renders a `` element.

Panel Props:

Prop Type Default Description
hiddenUntilFound boolean false Allows the browser's built-in page search to find and expand the panel contents. Overrides the keepMounted prop and uses hidden="until-found" to hide the element without removing it from the DOM.
className string | ((state: Collapsible.Panel.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Collapsible.Panel.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted boolean false Whether to keep the element in the DOM while the panel is hidden. This prop is ignored when hiddenUntilFound is used.
render ReactElement | ((props: HTMLProps, state: Collapsible.Panel.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Panel Data Attributes:

Attribute Type Description
data-open - Present when the collapsible panel is open.
data-closed - Present when the collapsible panel is closed.
data-starting-style - Present when the panel begins animating in.
data-ending-style - Present when the panel is animating out.

Panel CSS Variables:

Variable Type Description
--collapsible-panel-height number The collapsible panel's height.
--collapsible-panel-width number The collapsible panel's width.

Panel.Props

Re-export of Panel props.

Panel.State

typescript
type CollapsiblePanelState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the collapsible panel is currently open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
};

Additional Types

CollapsiblePanelCssVariables

CSS variables of Panel.

typescript
declare namespace CollapsiblePanelCssVariables {
  /**
   * The collapsible panel's height.
   * @type number
   */
  const collapsiblePanelHeight: '--collapsible-panel-height';
  /**
   * The collapsible panel's width.
   * @type number
   */
  const collapsiblePanelWidth: '--collapsible-panel-width';
}

CollapsiblePanelDataAttributes

Data attributes of Panel.

typescript
declare namespace CollapsiblePanelDataAttributes {
  /** Present when the collapsible panel is open. */
  const open: 'data-open';
  /** Present when the collapsible panel is closed. */
  const closed: 'data-closed';
  /** Present when the panel begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the panel is animating out. */
  const endingStyle: 'data-ending-style';
}

CollapsibleRootDataAttributes

Data attributes of Root.

typescript
declare namespace CollapsibleRootDataAttributes {
  /** Present when the collapsible is open. */
  const open: 'data-open';
  /** Present when the collapsible is closed. */
  const closed: 'data-closed';
  /** Present when the collapsible begins animating in. */
  const startingStyle: 'data-starting-style';
  /** Present when the collapsible is animating out. */
  const endingStyle: 'data-ending-style';
}

CollapsibleTriggerDataAttributes

Data attributes of Trigger.

typescript
declare namespace CollapsibleTriggerDataAttributes {
  /** Present when the collapsible panel is open. */
  const panelOpen: 'data-panel-open';
}

Export Groups

  • Collapsible.Root: Collapsible.Root, Collapsible.Root.State, Collapsible.Root.Props, Collapsible.Root.ChangeEventReason, Collapsible.Root.ChangeEventDetails
  • Collapsible.Trigger: Collapsible.Trigger, Collapsible.Trigger.State, Collapsible.Trigger.Props
  • Collapsible.Panel: Collapsible.Panel, Collapsible.Panel.State, Collapsible.Panel.Props
  • Default: CollapsibleRootDataAttributes, CollapsibleTriggerDataAttributes, CollapsiblePanelCssVariables, CollapsiblePanelDataAttributes, CollapsibleRootState, CollapsibleRootProps, CollapsibleRootChangeEventReason, CollapsibleRootChangeEventDetails, CollapsibleTriggerState, CollapsibleTriggerProps, CollapsiblePanelState, CollapsiblePanelProps

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

  • Collapsible.Root.State: CollapsibleRootState
  • Collapsible.Root.Props: CollapsibleRootProps
  • Collapsible.Root.ChangeEventReason: CollapsibleRootChangeEventReason
  • Collapsible.Root.ChangeEventDetails: CollapsibleRootChangeEventDetails
  • Collapsible.Trigger.State: CollapsibleTriggerState
  • Collapsible.Trigger.Props: CollapsibleTriggerProps
  • Collapsible.Panel.State: CollapsiblePanelState
  • Collapsible.Panel.Props: CollapsiblePanelProps

Src App (Docs) React Components Combobox Page (`docs/src/app/(docs)/react/components/combobox/page.mdx`)

Combobox

An input combined with a list of predefined items to select.

import { DemoComboboxHero } from './demos/hero';

Usage guidelines

  • Combobox is a filterable Select: Use Combobox when the input is restricted to a set of predefined selectable items, similar to Select but whose items are filterable using an input. Prefer using Combobox over Select when the number of items is sufficiently large to warrant filtering.
  • Avoid for simple search widgets: Combobox does not allow free-form text input. For search widgets, consider using Autocomplete instead.
  • Avoid when not rendering an input: Use Select instead of Combobox if no input is being rendered, which includes accessibility features specific to a listbox without an input.
  • Form controls must have an accessible name: If <Combobox.Input> is the form control, label it with a native <label> or <Field.Label>, or provide an aria-label when no visible label is rendered. <Combobox.Label> labels <Combobox.Trigger> and is intended for the input-inside-popup pattern, where the trigger is the form control. See the forms guide.
  • Closing animations: The popup stays rendered until its closing animation finishes. See JavaScript animations for animating it with Motion and for manual control.

Anatomy

Import the components and place them together:

jsx title="anatomy"
import { Combobox } from '@base-ui/react/combobox';

<Combobox.Root>
  <Combobox.Label />

  <Combobox.InputGroup>
    <Combobox.Input />
    <Combobox.Trigger />
    <Combobox.Icon />
    <Combobox.Clear />
    <Combobox.Value />

    <Combobox.Chips>
      <Combobox.Chip>
        <Combobox.ChipRemove />
      </Combobox.Chip>
    </Combobox.Chips>
  </Combobox.InputGroup>

  <Combobox.Portal>
    <Combobox.Backdrop />
    <Combobox.Positioner>
      <Combobox.Popup>
        <Combobox.Arrow />

        <Combobox.Status />
        <Combobox.Empty />

        <Combobox.List>
          <Combobox.Row>
            <Combobox.Item>
              <Combobox.ItemIndicator />
            </Combobox.Item>
          </Combobox.Row>

          <Combobox.Separator />

          <Combobox.Group>
            <Combobox.GroupLabel />
          </Combobox.Group>

          <Combobox.Collection />
        </Combobox.List>
      </Combobox.Popup>
    </Combobox.Positioner>
  </Combobox.Portal>
</Combobox.Root>;

Item values

Each <Combobox.Item> takes a value prop identifying it. Pass the item being rendered:

jsx title="using item objects as values"
<Combobox.List>
  {(item) => (
    <Combobox.Item key={item.id} value={item}>
      {item.label}
    </Combobox.Item>
  )}
</Combobox.List>

That item is what value, defaultValue, and onValueChange receive. To store IDs instead, see Value selection with IDs.

Examples

Typed wrapper component

The following example shows a typed wrapper around the Combobox component with correct type inference and type safety:

tsx title="specifying generic type parameters"
import * as React from 'react';
import { Combobox } from '@base-ui/react/combobox';

export function MyCombobox<Value, Multiple extends boolean | undefined = false, Item = Value>(
  props: Combobox.Root.Props<Value, Multiple, Item>,
): React.JSX.Element {
  return <Combobox.Root {...props}>{/* ... */}</Combobox.Root>;
}

The third Item type parameter is what lets the wrapper accept a Combobox.createItems() collection, whose rendered item type differs from its selection value. Omit it and a collection infers Value as the source item type, surfacing an error on defaultValue rather than on items.

Value selection with IDs

When your app stores IDs rather than item objects, use Combobox.createItems with getValue and getLabel to derive each item's selection value and display label.

With static data, create the collection at module scope. The accessor parameters are inferred from users. Pass the derived ID to the value prop of <Combobox.Item>, not the item being rendered:

jsx title="using item ids as values"
const items = Combobox.createItems(users, {
  getValue: (user) => user.id,
  getLabel: (user) => user.name,
});

<Combobox.Root items={items}>
  <Combobox.List>
    {(user) => (
      <Combobox.Item key={user.id} value={user.id}>
        {user.name}
      </Combobox.Item>
    )}
  </Combobox.List>
</Combobox.Root>;

Selection props and events use the derived IDs, while list rendering continues to receive the original items. The derived label is also used for filtering and typeahead.

When the data is loaded or replaced at runtime, memoize the collection on it so that it is rebuilt only when the data changes:

jsx title="creating a collection from dynamic data"
const items = React.useMemo(
  () =>
    Combobox.createItems(users, {
      getValue: (user) => user.id,
      getLabel: (user) => user.name,
    }),
  [users],
);

import { DemoComboboxCreateItems } from './demos/create-items';

As a rule of thumb, use primitive items for simple lists, object values when the selected record is useful application state, and createItems() when selection should use a stable primitive ID while rendering and filtering still use object records.

Stable IDs preserve item matching when an async data library replaces row objects during a refetch. With object values, use isItemEqualToValue to compare their IDs instead.

When results are filtered externally (for example, by a server-side search), items represents records known to the app, while filteredItems represents the current result window displayed in the popup. Pass source items rather than derived values to filteredItems, preserving the flat or grouped structure of items:

tsx title="displaying a window of async results"
const items = React.useMemo(
  () =>
    Combobox.createItems(knownUsers, {
      getValue: (user) => user.id,
      getLabel: (user) => user.name,
    }),
  [knownUsers],
);

<Combobox.Root
  items={items}
  filteredItems={searchResults}
  value={selectedUserId}
  onValueChange={setSelectedUserId}
/>;

Include the selected user's record in knownUsers so its label remains available when it is outside searchResults. Alternatively, provide itemToStringLabel when the label can be derived from the selected value alone.

Multiple select

The combobox can allow multiple selections by adding the multiple prop to <Combobox.Root>.
Selection chips are rendered with <Combobox.Chip> inside the input that can be removed.

import { DemoComboboxMultiple } from './demos/multiple';

In order for screen readers to announce how to reach and remove the chips, add aria-description to <Combobox.Chip> and <Combobox.Input>, alongside the aria-label on <Combobox.Chips> and <Combobox.ChipRemove>.
Base UI does not ship these strings. Translate them together with the rest of your interface.

Visible chips can be limited by slicing the selected values rendered in <Combobox.Value>:

tsx title="limiting visible chips"
const CHIP_LIMIT = 3;

<Combobox.Value>
  {(selectedValue: string[]) => {
    // @highlight-start
    const visibleValue = selectedValue.slice(0, CHIP_LIMIT);
    const hiddenCount = selectedValue.length - visibleValue.length;
    // @highlight-end
    return (
      <>
        {visibleValue.map((item) => (
          <Combobox.Chip key={item} aria-description="Press Backspace or Delete to remove">
            {item}
            <Combobox.ChipRemove aria-label={`Remove ${item}`} />
          </Combobox.Chip>
        ))}
        {/* @highlight-start */}
        {hiddenCount > 0 && <span>{`+${hiddenCount} more`}</span>}
        {/* @highlight-end */}
        <Combobox.Input
          aria-description={
            selectedValue.length > 0
              ? `${selectedValue.length} selected. From the start of the input, press Left Arrow to focus the selected items`
              : undefined
          }
        />
      </>
    );
  }}
</Combobox.Value>;

Keeping the filter after selection

In multiple mode, selecting an item clears the typed filter and closes the popup when the input is rendered outside it. To let users pick several results from one query, cancel the relevant change request.

Which request to cancel depends on the input's placement. When the input is outside the popup, cancel the item-press close request in onOpenChange. When it is inside, cancel the clear request in onInputValueChange, marked with eventDetails.isItemPress.

jsx title="input outside the popup"
<Combobox.Root
  multiple
  onOpenChange={(open, eventDetails) => {
    if (!open && eventDetails.reason === 'item-press') {
      eventDetails.cancel();
    }
  }}
>
  {/* ... */}
</Combobox.Root>
jsx title="input inside the popup"
<Combobox.Root
  multiple
  onInputValueChange={(value, eventDetails) => {
    if (eventDetails.isItemPress) {
      eventDetails.cancel();
    }
  }}
>
  {/* ... */}
</Combobox.Root>

The typed filter still resets once the popup closes.

Input inside popup

<Combobox.Input> can be rendered inside <Combobox.Popup> to create a searchable select popup.

import { DemoComboboxInputInsidePopup } from './demos/input-inside-popup';

Use <Combobox.Label> to provide a visible label for the combobox trigger in this pattern:

tsx title="using combobox.label to label a combobox"
<Combobox.Root>
  {/* @highlight */}
  <Combobox.Label>Favorite fruit</Combobox.Label>
  {/* ... */}
</Combobox.Root>

<Combobox.Label> renders a ``, so clicking it focuses the combobox trigger without opening the popup.

Grouped

Organize related options with <Combobox.Group> and <Combobox.GroupLabel> to add section headings inside the popup.

Groups are represented by an array of objects with an items property, which itself is an array of individual items for each group. An extra property, such as value, can be provided for the heading text when rendering the group label.

tsx title="example"
interface ProduceGroupItem {
  value: string;
  // @highlight
  items: string[];
}

const groups: ProduceGroupItem[] = [
  {
    value: 'Fruits',
    // @highlight
    items: ['Apple', 'Banana', 'Orange'],
  },
  {
    value: 'Vegetables',
    // @highlight
    items: ['Carrot', 'Lettuce', 'Spinach'],
  },
];

import { DemoComboboxGrouped } from './demos/grouped';

Async search (single)

Load items from a remote source by fetching on input changes. Keep the selected item in the items list so it remains available while new results stream in. This pattern avoids needing to load items upfront.

import { DemoComboboxAsyncSingle } from './demos/async-single';

Async search (multiple)

Load items from a remote source by fetching on input changes while supporting multiple selections. Selected items remain available in the list while new matches stream in. This pattern avoids needing to load items upfront.

import { DemoComboboxAsyncMultiple } from './demos/async-multiple';

Creatable

Create a new item when the filter matches no items, opening a creation <Dialog>.

import { DemoComboboxCreatable } from './demos/creatable';

Virtualized

Efficiently handle large datasets using a virtualization library like @tanstack/react-virtual.

import { DemoComboboxVirtualized } from './demos/virtualized';

Memoizing items

Memoizing each item is a simpler alternative to virtualization for datasets up to roughly 1,000 items. Wrap each item in React.memo and pass the item as a prop so unchanged items skip re-rendering. While memoization speeds up typing, it does not speed up opening; with a large enough number of items, the mount cost dominates, and virtualization becomes necessary to keep the open interaction fast on low-end devices.

tsx title="memoizing list items"
interface Fruit {
  id: string;
  label: string;
}

const FruitItem = React.memo(function FruitItem({ item }: { item: Fruit }) {
  return (
    <Combobox.Item value={item}>
      <Combobox.ItemIndicator />
      <span>{item.label}</span>
    </Combobox.Item>
  );
});

<Combobox.List>{(item: Fruit) => <FruitItem key={item.id} item={item} />}</Combobox.List>;

API reference

import { TypesCombobox } from './types';

Root

<TypesCombobox.Root />

Label

<TypesCombobox.Label />

Value

<TypesCombobox.Value />

Icon

<TypesCombobox.Icon />

Input

<TypesCombobox.Input />

InputGroup

<TypesCombobox.InputGroup />

Clear

<TypesCombobox.Clear />

Trigger

<TypesCombobox.Trigger />

Chips

<TypesCombobox.Chips />

Chip

<TypesCombobox.Chip />

ChipRemove

<TypesCombobox.ChipRemove />

List

<TypesCombobox.List />

Portal

<TypesCombobox.Portal />

Backdrop

<TypesCombobox.Backdrop />

Positioner

<TypesCombobox.Positioner />

<TypesCombobox.Popup />

Arrow

<TypesCombobox.Arrow />

Status

<TypesCombobox.Status />

Empty

<TypesCombobox.Empty />

Collection

<TypesCombobox.Collection />

Row

<TypesCombobox.Row />

Item

<TypesCombobox.Item />

ItemIndicator

<TypesCombobox.ItemIndicator />

Group

<TypesCombobox.Group />

GroupLabel

<TypesCombobox.GroupLabel />

Separator

<TypesCombobox.Separator />

useFilter

Matches items against a query using Intl.Collator for robust string matching.
This hook is used when externally filtering items.
Pass the result to the filter prop of <Combobox.Root>.

<TypesCombobox.useFilter hideDescription />

useFilteredItems

Returns the internally filtered items when called inside <Combobox.Root>.

<TypesCombobox.useFilteredItems hideDescription />

createItems

Normalizes items into a collection for the items prop of <Combobox.Root>, deriving each item's selection value and label before rendering.

<TypesCombobox.createItems hideDescription />

export const metadata = {
keywords: [
'React Combobox',
'Combobox Component',
'Combo Box',
'Filterable Select',
'Searchable Dropdown',
'Editable Select',
'Typeahead Select',
'Autocomplete Dropdown',
'Tags Input',
'Chip Input',
'Token Input',
'Multi-Value Input',
'Multiple Select Combobox',
'Async Combobox',
'Accessible Combobox',
'Base UI',
],
};

Src App (Docs) React Components Combobox Types (`docs/src/app/(docs)/react/components/combobox/types.md`)

Combobox

API Reference

Root

Groups all parts of the combobox.
Doesn't render its own HTML element.

Root Props:

Prop Type Default Description
name string - Identifies the field when a form is submitted.
defaultValue Value[] | Value | null - The uncontrolled selected value of the combobox when it's initially rendered. To render a controlled combobox, use the value prop instead.
value Value[] | Value | null - The selected value of the combobox. Use when controlled.
onValueChange ((value: Value[] | Value | null, eventDetails: Combobox.Root.ChangeEventDetails) => void) - Event handler called when the selected value of the combobox changes.
defaultInputValue string | number | string[] - The uncontrolled input value when initially rendered. To render a controlled input, use the inputValue prop instead.
inputValue string | string[] | number - The input value of the combobox. Use when controlled.
onInputValueChange ((inputValue: string, eventDetails: Combobox.Root.ChangeEventDetails) => void) - Event handler called when the input value changes.
defaultOpen boolean false Whether the popup is initially open. To render a controlled popup, use the open prop instead.
open boolean - Whether the popup is currently open. Use when controlled.
onOpenChange ((open: boolean, eventDetails: Combobox.Root.OpenChangeEventDetails) => void) - Event handler called when the popup is opened or closed.
autoHighlight boolean false Whether the first matching item is highlighted automatically while filtering.
highlightItemOnHover boolean true Whether moving the pointer over items should highlight them. Disabling this prop allows CSS :hover to be differentiated from the :focus (data-highlighted) state.
actionsRef React.RefObject<Combobox.Root.Actions | null> - A ref to imperative actions. unmount: Ends the closing phase of the combobox after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the combobox completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.close: Closes the combobox imperatively when called.
autoComplete string - Provides a hint to the browser for autofill.
filter ((item: Item, query: string, itemToString?: ((item: Item) => string)) => boolean) | null - ComboboxFilter function used to match items vs input query. Receives the source item, which is the derived value's item when items is a createItems() collection, and the item itself otherwise.
filteredItems Item[] | Group[] - Filtered items to display in the list. When provided, the list uses these items instead of filtering the items prop internally. When items is also provided, this array must preserve its flat or grouped structure. With a createItems() collection, pass source items rather than derived values. Nullish entries are not supported, as in items. Use when you want to control filtering logic externally with the useFilter() hook.
form string - Identifies the form that owns the internal input. Useful when the combobox is rendered outside the form.
grid boolean false Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
inline boolean false Whether the list is rendered inline without using the component's own popup. Specify open unconditionally in conjunction with this prop so the list is considered visible: <Combobox.Root inline open> In a Combobox.Root > Dialog.Root composition, bind the Combobox's open and onOpenChange props to the Dialog's open and onOpenChange state instead so the component resets its transient state (filter query, highlighted item, and input value) when the dialog closes.
isItemEqualToValue ((itemValue: Value, value: Value) => boolean) - Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. With a createItems() collection, both arguments are derived values. Defaults to Object.is comparison.
itemToStringLabel ((itemValue: Value) => string) - When the item values are objects (<Combobox.Item value={object}>), this function converts the object value to a string representation for display in the input. If the shape of the object is { value, label }, the label will be used automatically without needing to specify this prop. With a createItems() collection, this receives the derived value, and the collection's getLabel takes precedence for values it can resolve.
itemToStringValue ((itemValue: Value) => string) - When the item values are objects (<Combobox.Item value={object}>), this function converts the object value to a string representation for form submission. If the shape of the object is { value, label }, the value will be used automatically without needing to specify this prop. With a createItems() collection, this receives the derived value.
items any[] | Group[] | ComboboxItemCollection - The items to be displayed in the list. Can be a flat array of items, an array of groups with items, or a collection created by the createItems() function, which derives each item's selection value and label. Nullish entries are not supported: remove them from the data before passing it.
limit number -1 The maximum number of items to display in the list.
locale Intl.LocalesArgument - The locale to use for string comparison. Defaults to the user's runtime locale.
loopFocus boolean true Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing ArrowDown again from the input, or the last item can be reached by pressing ArrowUp from the input. The input is always included in the focus loop per ARIA Authoring Practices. When disabled, focus does not move when on the last element and the user presses ArrowDown, or when on the first element and the user presses ArrowUp.
modal boolean false Determines if the popup enters a modal state when open. true: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.false: user interaction with the rest of the document is allowed. On touch devices, a true modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
multiple boolean false Whether multiple items can be selected.
onItemHighlighted ((highlightedValue: Value | undefined, eventDetails: Combobox.Root.HighlightEventDetails) => void) - Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or undefined if no item is highlighted) and event details with a reason property describing why the highlight changed. The reason can be: 'keyboard': the highlight changed due to keyboard navigation.'pointer': the highlight changed due to pointer hovering. The event may be a MouseEvent rather than a PointerEvent.'none': the highlight changed for another reason, such as typing, autoHighlight, the item list changing, or the popup opening or closing.
onOpenChangeComplete ((open: boolean) => void) - Event handler called after any animations complete when the popup is opened or closed.
openOnInputClick boolean true Whether the popup opens when clicking the input.
virtualized boolean false Whether the items are being externally virtualized.
disabled boolean false Whether the component should ignore user interaction.
readOnly boolean false Whether the user should be unable to choose a different option from the popup.
required boolean false Whether the user must choose a value before submitting a form.
inputRef React.Ref<HTMLInputElement> - A ref to the hidden input element.
id string - The id of the component.
children React.ReactNode - -

autoComplete Prop References:

Root.Props

Re-export of Root props.

Root.State

typescript
type ComboboxRootState = {};

Root.Actions

typescript
type ComboboxRootActions = { unmount: () => void; close: () => void };

Root.ChangeEventReason

typescript
type ComboboxRootChangeEventReason =
  | 'trigger-press'
  | 'input-press'
  | 'outside-press'
  | 'item-press'
  | 'close-press'
  | 'escape-key'
  | 'list-navigation'
  | 'focus-out'
  | 'input-change'
  | 'input-clear'
  | 'clear-press'
  | 'chip-remove-press'
  | 'cancel-open'
  | 'imperative-action'
  | 'none';

Root.ChangeEventDetails

text
/* Detailed source-code truncated for AI context efficiency. */

Root.HighlightEventReason

typescript
type ComboboxRootHighlightEventReason = 'keyboard' | 'pointer' | 'none';

Root.HighlightEventDetails

typescript
type ComboboxRootHighlightEventDetails =
  | { reason: 'none'; event: Event; index: number }
  | { reason: 'pointer'; event: MouseEvent | PointerEvent; index: number }
  | { reason: 'keyboard'; event: KeyboardEvent; index: number };

Root.OpenChangeEventDetails

text
/* Detailed source-code truncated for AI context efficiency. */

Trigger

A button that opens the popup.
Renders a `` element.

Trigger Props:

Prop Type Default Description
nativeButton boolean true Whether the component renders a native element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example,).
disabled boolean false Whether the component should ignore user interaction.
className string | ((state: Combobox.Trigger.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Combobox.Trigger.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Combobox.Trigger.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Trigger Data Attributes:

Attribute Type Description
data-popup-open - Present when the corresponding popup is open.
data-popup-side 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null Indicates which side the corresponding popup is positioned relative to its anchor.
data-list-empty - Present when the corresponding items list is empty.
data-pressed - Present when the trigger is pressed.
data-disabled - Present when the component is disabled.
data-readonly - Present when the component is readonly.
data-required - Present when the component is required.
data-valid - Present when the component is in a valid state (when wrapped in Field.Root).
data-invalid - Present when the component is in an invalid state (when wrapped in Field.Root).
data-dirty - Present when the component's value has changed (when wrapped in Field.Root).
data-touched - Present when the component has been touched (when wrapped in Field.Root).
data-filled - Present when the component has a value (when wrapped in Field.Root).
data-focused - Present when the trigger is focused (when wrapped in Field.Root).
data-placeholder - Present when the combobox doesn't have a value.

Trigger.Props

Re-export of Trigger props.

Trigger.State

typescript
type ComboboxTriggerState = {
  /** Whether the popup is open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the component should ignore user edits. */
  readOnly: boolean;
  /** Indicates which side the corresponding popup is positioned relative to its anchor. */
  popupSide: Side | null;
  /** Present when the corresponding items list is empty. */
  listEmpty: boolean;
  /** Whether the combobox doesn't have a value. */
  placeholder: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Value

The current value of the combobox.
Doesn't render its own HTML element.

Value Props:

Prop Type Default Description
placeholder React.ReactNode - The placeholder value to display when no value is selected. This is overridden by children if specified, or by a null item's label in items.
children React.ReactNode | ((selectedValue: any) => React.ReactNode) - Accepts a function that returns a ReactNode to format the selected value. Treat the value as read-only: in multiple mode it may be a shared frozen array when nothing is selected.

Value.Props

Re-export of Value props.

Value.State

typescript
type ComboboxValueState = {};

Input

A text input to search for items in the list.
Renders an `` element.

Input Props:

Prop Type Default Description
disabled boolean false Whether the component should ignore user interaction.
className string | ((state: Combobox.Input.State) => string | undefined) - CSS class applied to the element, or a function that returns a class based on the component's state.
style React.CSSProperties | ((state: Combobox.Input.State) => React.CSSProperties | undefined) - Style applied to the element, or a function that returns a style object based on the component's state.
render ReactElement | ((props: HTMLProps, state: Combobox.Input.State) => ReactElement) - Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render.

Input Data Attributes:

Attribute Type Description
data-popup-open - Present when the corresponding popup is open.
data-popup-side 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null Indicates which side the corresponding popup is positioned relative to its anchor.
data-list-empty - Present when the corresponding items list is empty.
data-pressed - Present when the input is pressed.
data-disabled - Present when the component is disabled.
data-readonly - Present when the component is readonly.
data-required - Present when the component is required.
data-valid - Present when the component is in a valid state (when wrapped in Field.Root).
data-invalid - Present when the component is in an invalid state (when wrapped in Field.Root).
data-dirty - Present when the component's value has changed (when wrapped in Field.Root).
data-touched - Present when the component has been touched (when wrapped in Field.Root).
data-filled - Present when the component has a value (when wrapped in Field.Root).
data-focused - Present when the input is focused (when wrapped in Field.Root).

Input.Props

Re-export of Input props.

Input.State

typescript
type ComboboxInputState = {
  /** Whether the corresponding popup is open. */
  open: boolean;
  /** Indicates whic

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#accessibility Browse accessibility catalog → #base-ui Browse base-ui catalog → #components Browse components catalog → #design-system Browse design-system catalog → #react Browse react catalog → #react-components Browse react-components catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →