---
title: Quick start
subtitle: A quick guide to getting started with Base UI.
description: A quick guide to getting started with Base UI.
---
# Quick start
A quick guide to getting started with Base UI.
## Install the library
Install Base UI using a package manager.
### pnpm
```bash
pnpm add @base-ui/react
```
### npm
```bash
npm i @base-ui/react
```
### yarn
```bash
yarn add @base-ui/react
```
### bun
```bash
bun add @base-ui/react
```
All components are included in a single package. Base UI is tree-shakable, so your app bundle will contain only the components that you actually use.
## Set up
### Portals
Base UI uses portals for components that render popups, such as Dialog and Popover.
To make portaled components always appear on top of the entire page, add the following style to your application layout root:
```tsx title="layout.tsx"
{/* prettier-ignore */}
{children}
```
```css title="styles.css"
.root {
isolation: isolate;
}
```
This style creates a separate stacking context for your application's `.root` element.
This way, popups always appear above the page contents, and any `z-index` property in your styles won't interfere with them.
### iOS 26+ Safari
Starting with iOS 26, Safari allows content beneath the UI chrome to be visible. Backdrops such as those used by dialogs must use `position: absolute` instead of `position: fixed` to cover the entire visual viewport. For this to work after the page is scrolled, the following style must be added to your global styles:
```css title="styles.css"
body {
position: relative;
}
```
## Assemble a component
This demo shows you how to import a [Popover](/react/components/popover.md) component, assemble its parts, and apply styles.
There are examples for both Tailwind and CSS Modules below, but since Base UI is unstyled, you can use CSS-in-JS, plain CSS, or any other styling solution you prefer.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* index.tsx */
import { Popover } from '@base-ui/react/popover';
import { BellIcon, ArrowSvg } from './icons-tw';
export default function ExamplePopover() {
return (
Notifications
You are all caught up. Good job!
);
}
```
```tsx
/* icons-tw.tsx */
import * as React from 'react';
export function ArrowSvg(props: React.ComponentProps<'svg'>) {
return (
);
}
export function BellIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
export function UserIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
export function ListIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
### CSS Modules
This example shows how to implement the component using CSS Modules.
```css
/* index.module.css */
.IconButton {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
width: 2.5rem;
height: 2.5rem;
padding: 0;
margin: 0;
outline: 0;
border: 1px solid var(--color-gray-200);
border-radius: 0.375rem;
background-color: var(--color-gray-50);
color: var(--color-gray-900);
user-select: none;
@media (hover: hover) {
&:hover {
background-color: var(--color-gray-100);
}
}
&:active {
background-color: var(--color-gray-100);
}
&[data-popup-open] {
background-color: var(--color-gray-100);
}
&:focus-visible {
outline: 2px solid var(--color-blue);
outline-offset: -1px;
}
}
.Icon {
width: 1.25rem;
height: 1.25rem;
}
.Positioner {
width: var(--positioner-width);
height: var(--positioner-height);
max-width: var(--available-width);
}
.Popup {
box-sizing: border-box;
padding: 1rem 1.5rem;
border-radius: 0.5rem;
background-color: canvas;
color: var(--color-gray-900);
transform-origin: var(--transform-origin);
transition:
transform 150ms,
opacity 150ms;
width: var(--popup-width, auto);
height: var(--popup-height, auto);
max-width: 500px;
&[data-starting-style],
&[data-ending-style] {
opacity: 0;
transform: scale(0.9);
}
@media (prefers-color-scheme: light) {
outline: 1px solid var(--color-gray-200);
box-shadow:
0 10px 15px -3px var(--color-gray-200),
0 4px 6px -4px var(--color-gray-200);
}
@media (prefers-color-scheme: dark) {
outline: 1px solid var(--color-gray-300);
outline-offset: -1px;
}
}
.Arrow {
display: flex;
&[data-side='top'] {
bottom: -8px;
rotate: 180deg;
}
&[data-side='bottom'] {
top: -8px;
rotate: 0deg;
}
&[data-side='left'] {
right: -13px;
rotate: 90deg;
}
&[data-side='right'] {
left: -13px;
rotate: -90deg;
}
}
.ArrowFill {
fill: canvas;
}
.ArrowOuterStroke {
@media (prefers-color-scheme: light) {
fill: var(--color-gray-200);
}
}
.ArrowInnerStroke {
@media (prefers-color-scheme: dark) {
fill: var(--color-gray-300);
}
}
.Title {
margin: 0;
font-size: 1rem;
line-height: 1.5rem;
font-weight: 700;
}
.Description {
margin: 0;
font-size: 1rem;
line-height: 1.5rem;
color: var(--color-gray-600);
}
.Container {
display: flex;
gap: 8px;
flex-wrap: wrap;
justify-content: center;
}
.Button {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
gap: 0.375rem;
height: 2.5rem;
padding: 0 0.875rem;
margin: 0;
outline: 0;
border: 1px solid var(--color-gray-200);
border-radius: 0.375rem;
background-color: var(--color-gray-50);
font-family: inherit;
font-size: 1rem;
font-weight: 400;
line-height: 1.5rem;
color: var(--color-gray-900);
user-select: none;
@media (hover: hover) {
&:hover {
background-color: var(--color-gray-100);
}
}
&:active {
background-color: var(--color-gray-100);
}
&:focus-visible {
outline: 2px solid var(--color-blue);
outline-offset: -1px;
}
}
```
```tsx
/* index.tsx */
import * as React from 'react';
import { Popover } from '@base-ui/react/popover';
import styles from './index.module.css';
export default function ExamplePopover() {
return (
Notifications
You are all caught up. Good job!
);
}
function ArrowSvg(props: React.ComponentProps<'svg'>) {
return (
);
}
function BellIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
## Next steps
This walkthrough outlines the basics of putting together a Base UI component.
Browse the rest of the documentation to see what components are available in the library and how to use them.
## Working with LLMs
For those of you working with LLMs, each docs page has a "View as Markdown" link at the top, which can be shared with AI chat assistants to help them understand Base UI concepts and component APIs.
Additionally, there is an ["llms.txt"](/llms.txt) link in the "Handbook" section of the navigation sidebar, which you can feed to AI chat assistants to help them navigate the docs.