> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mui/base-ui/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Install Base UI in your React project and configure your development environment.
# Installation
Get started with Base UI by installing the package and setting up your project.
## Install Base UI
Install `@base-ui/react` using your preferred package manager:
```bash npm theme={null}
npm install @base-ui/react
```
```bash yarn theme={null}
yarn add @base-ui/react
```
```bash pnpm theme={null}
pnpm add @base-ui/react
```
All Base UI components are included in a single package. The library is tree-shakable, so your bundle will only contain the components you actually use.
Base UI requires React as a peer dependency. Make sure you have one of the supported React versions installed:
```json package.json theme={null}
{
"dependencies": {
"react": "^17.0.0 || ^18.0.0 || ^19.0.0",
"react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
}
}
```
Base UI supports React 17, 18, and 19. TypeScript types are also available if you use `@types/react`.
If you're using TypeScript, Base UI provides comprehensive type definitions out of the box. No additional setup is required.
The package includes TypeScript definitions for all components and their props:
```typescript theme={null}
import { Button } from '@base-ui/react/button';
import type { ButtonProps } from '@base-ui/react/button';
// Full type safety and autocomplete support
const MyButton: React.FC = (props) => {
return ;
};
```
`@types/react` is an optional peer dependency. If you're using TypeScript, make sure to install it for the best development experience.
## Project Setup
### Portals Configuration
Base UI uses portals for components that render popups (Dialog, Popover, Tooltip, Menu, etc.). To ensure portaled components always appear on top of your page content, add this style to your application layout:
```tsx layout.tsx theme={null}
export default function Layout({ children }) {
return (
{children}
);
}
```
```css styles.css theme={null}
.root {
isolation: isolate;
}
```
This creates a separate stacking context for your application, ensuring popups always appear above page contents and preventing `z-index` conflicts.
### iOS Safari 26+ Support
Starting with iOS 26, Safari requires a specific configuration for dialog backdrops to work correctly.
Add this style to your global CSS to ensure backdrops cover the entire viewport after scrolling:
```css global.css theme={null}
body {
position: relative;
}
```
This is necessary because iOS 26+ Safari allows content beneath the UI chrome to be visible, requiring backdrops to use `position: absolute` instead of `position: fixed`.
## Verify Installation
Test your installation by importing and using a simple component:
```tsx App.tsx theme={null}
import { Button } from '@base-ui/react/button';
function App() {
return (
);
}
export default App;
```
If the button renders and responds to clicks, your installation is successful!
## Package Exports
Base UI provides granular exports for optimal tree-shaking. You can import components individually:
```tsx theme={null}
// Import individual components
import { Button } from '@base-ui/react/button';
import { Dialog } from '@base-ui/react/dialog';
import { Popover } from '@base-ui/react/popover';
// Or import from the main package
import { Button, Dialog, Popover } from '@base-ui/react';
```
Importing from specific paths (e.g., `@base-ui/react/button`) can provide better IDE autocomplete in some editors, but both approaches are equally tree-shakable.
## Next Steps
Build your first styled component with Base UI
Explore all available components