Skip to content
🚀 MUI X v6 is out! Discover what's new and get started now!
Edit this page

Quickstart

Get started with Base UI, a library of headless ("unstyled") React UI components and low-level hooks.

Installation

@mui/base is completely standalone – run one of the following commands to add Base UI to your React project:

With npm

<span class="token function">npm</span> <span class="token function">install</span> @mui/base

With yarn

<span class="token function">yarn</span> <span class="token function">add</span> @mui/base

With pnpm

<span class="token function">pnpm</span> <span class="token function">add</span> @mui/base

Peer dependencies

Please note that react and react-dom are peer dependencies too:

<span class="token property">"peerDependencies"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
  <span class="token property">"react"</span><span class="token operator">:</span> <span class="token string">"^17.0.0 || ^18.0.0"</span><span class="token punctuation">,</span>
  <span class="token property">"react-dom"</span><span class="token operator">:</span> <span class="token string">"^17.0.0 || ^18.0.0"</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>

Implementing a Button

This is a quick tutorial that goes through the basics of using and styling Base UI components by replicating a button from GitHub's UI, using their Primer design system as a reference.

Components and hooks

Base UI provides a <Button /> component and a useButton hook. Both can be used to build a button, and each has its own benefits and trade-offs—see Components vs. hooks for details.

The code snippets below demonstrate the basic implementation of each:

Button component

<span class="token keyword">import</span> <span class="token operator">*</span> <span class="token keyword">as</span> React <span class="token keyword">from</span> <span class="token string">'react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> Button <span class="token keyword">from</span> <span class="token string">'@mui/base/Button'</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Button</span></span><span class="token punctuation">></span></span>Click Me<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Button</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

useButton hook

<span class="token keyword">import</span> <span class="token operator">*</span> <span class="token keyword">as</span> React <span class="token keyword">from</span> <span class="token string">'react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> useButton <span class="token keyword">from</span> <span class="token string">'@mui/base/useButton'</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">const</span> <span class="token punctuation">{</span> getRootProps <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">useButton</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>button</span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token spread"><span class="token punctuation">{</span><span class="token operator">...</span><span class="token function">getRootProps</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
      Click Me
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>button</span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Base UI comes with no styles or styling solution—here's what the Button component looks like out of the box:

You can use any styling method of your choice to make fully customizable components for your app. See Customization for more details on customization strategies.

Here are some styling examples:

Styling with CSS

Pass a className prop and use it as a styling hook:

<span class="token comment">/* styles.css */</span>

<span class="token selector">.btn</span> <span class="token punctuation">{</span>
  <span class="token property">background-color</span><span class="token punctuation">:</span> #1f883d<span class="token punctuation">;</span>
  <span class="token comment">/* the rest of the styles */</span>
<span class="token punctuation">}</span>

<span class="token comment">/* App.js */</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Button</span></span> <span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>btn<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Create Repository<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Button</span></span><span class="token punctuation">></span></span>

Base UI components like the Button come with a classes object (e.g. buttonClasses) that provides class hooks for styling a particular state.

<span class="token comment">/* To style the disabled state: */</span>

<span class="token selector">.$</span><span class="token punctuation">{</span>buttonClasses.disabled<span class="token punctuation">}</span> <span class="token punctuation">{</span> <span class="token comment">/* ".MuiButton-disabled" */</span>
  <span class="token property">cursor</span><span class="token punctuation">:</span> not-allowed<span class="token punctuation">;</span>
<span class="token punctuation">}</span>

The demo below shows how to create the Primer button using plain CSS with Base UI's Button component and useButton hook:

Styling with Tailwind CSS

After installing Tailwind CSS, pass its utility classes to className, as shown below:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Button</span></span> <span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>bg-green-600 rounded-md py-1 px-4...<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Create Repository<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Button</span></span><span class="token punctuation">></span></span>

The demo below shows how to build the Primer button using Tailwind CSS:

Styling with MUI System

MUI System is a small set of CSS utilties that provide a styled-components-like API for building out designs that adhere to a theme.

MUI System's core utility is a styled function that's equivalent to the styled() function in emotion and styled-components. Interpolations or arguments that are functions called by styled receive the theme from an upper ThemeProvider.

<span class="token keyword">import</span> <span class="token operator">*</span> <span class="token keyword">as</span> React <span class="token keyword">from</span> <span class="token string">'react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> ThemeProvider <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@emotion/react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> styled <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/system'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> Button <span class="token keyword">from</span> <span class="token string">'@mui/base/Button'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token punctuation">{</span>
  colors<span class="token operator">:</span> <span class="token punctuation">{</span>
    primary<span class="token operator">:</span> <span class="token string">'green'</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> GitHubButton <span class="token operator">=</span> <span class="token function">styled</span><span class="token punctuation">(</span>Button<span class="token punctuation">)</span><span class="token punctuation">(</span>
  <span class="token punctuation">(</span><span class="token punctuation">{</span> theme <span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">
    background-color: </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>theme<span class="token punctuation">.</span>colors<span class="token punctuation">.</span>primary <span class="token comment">/* => 'green' */</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">;
  </span><span class="token template-punctuation string">`</span></span><span class="token punctuation">,</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token function">render</span><span class="token punctuation">(</span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">ThemeProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>theme<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">GitHubButton</span></span><span class="token punctuation">></span></span>Create Repository<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">GitHubButton</span></span><span class="token punctuation">></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">ThemeProvider</span></span><span class="token punctuation">></span></span><span class="token punctuation">,</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

Most of the demos in the Base UI docs are styled with MUI System in this way. You can inspect the theme object used on this site in your browser console, or explore the default structure in the Material UI Default theme documentation.

The demos below show how to create the Primer button using MUI System:

Button Component with MUI System

<span class="token keyword">import</span> <span class="token operator">*</span> <span class="token keyword">as</span> React <span class="token keyword">from</span> <span class="token string">'react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> Button <span class="token keyword">from</span> <span class="token string">'@mui/base/Button'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> styled <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/system'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> GitHubButton <span class="token operator">=</span> <span class="token function">styled</span><span class="token punctuation">(</span>Button<span class="token punctuation">)</span><span class="token punctuation">(</span>
  <span class="token punctuation">(</span><span class="token punctuation">{</span> theme <span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">
    background-color: </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>theme<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>mode <span class="token operator">===</span> <span class="token string">'dark'</span> <span class="token operator">?</span> <span class="token string">'#238636'</span> <span class="token operator">:</span> <span class="token string">'#1f883d'</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">;
    </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span><span class="token operator">/</span><span class="token operator">*</span> <span class="token operator">...</span> the rest <span class="token keyword">of</span> the styles <span class="token operator">*</span><span class="token operator">/</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">
  </span><span class="token template-punctuation string">`</span></span><span class="token punctuation">,</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">GitHubButton</span></span><span class="token punctuation">></span></span>Create Repository<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">GitHubButton</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

useButton hook with MUI System

<span class="token keyword">import</span> <span class="token operator">*</span> <span class="token keyword">as</span> React <span class="token keyword">from</span> <span class="token string">'react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> useButton <span class="token keyword">from</span> <span class="token string">'@mui/base/useButton'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> styled <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/system'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> GitHubButton <span class="token operator">=</span> <span class="token function">styled</span><span class="token punctuation">(</span><span class="token string">'button'</span><span class="token punctuation">)</span><span class="token punctuation">(</span>
  <span class="token punctuation">(</span><span class="token punctuation">{</span> theme <span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">
    background-color: </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>theme<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>mode <span class="token operator">===</span> <span class="token string">'dark'</span> <span class="token operator">?</span> <span class="token string">'#238636'</span> <span class="token operator">:</span> <span class="token string">'#1f883d'</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">;
    </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span><span class="token operator">/</span><span class="token operator">*</span> <span class="token operator">...</span> the rest <span class="token keyword">of</span> the styles <span class="token operator">*</span><span class="token operator">/</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">
  </span><span class="token template-punctuation string">`</span></span><span class="token punctuation">,</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">const</span> <span class="token punctuation">{</span> getRootProps <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">useButton</span><span class="token punctuation">(</span><span class="token comment">/* props*/</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">GitHubButton</span></span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>button<span class="token punctuation">"</span></span> <span class="token spread"><span class="token punctuation">{</span><span class="token operator">...</span><span class="token function">getRootProps</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
      Create Repository
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">GitHubButton</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Using the sx prop

MUI System supports the sx prop, which provides a quick way to apply ad-hoc styles using theme-aware values to any component created with styled.

<span class="token keyword">const</span> GitHubButton <span class="token operator">=</span> <span class="token function">styled</span><span class="token punctuation">(</span>Button<span class="token punctuation">)</span><span class="token punctuation">(</span>
  <span class="token punctuation">(</span><span class="token punctuation">{</span> theme <span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">
    background-color: </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>theme<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>mode <span class="token operator">===</span> <span class="token string">'dark'</span> <span class="token operator">?</span> <span class="token string">'#238636'</span> <span class="token operator">:</span> <span class="token string">'#1f883d'</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">;
    margin: 0;
  </span><span class="token template-punctuation string">`</span></span><span class="token punctuation">,</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">GitHubButton</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> m<span class="token operator">:</span> <span class="token number">2</span> <span class="token comment">/* => margin: 16px */</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
      Create Repository
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">GitHubButton</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

The demo below shows how to build the Primer button using MUI System along with the sx prop:

Read the MUI System Usage doc for further details.