Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs] Remove or hide pages describing the old API #323

Merged
merged 2 commits into from
Apr 16, 2024
Merged

[docs] Remove or hide pages describing the old API #323

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
176fa12
[docs] Remove or hide pages describing the old API
michaldudak Apr 16, 2024
ba8d286
i18n
michaldudak Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/data/base/getting-started/overview/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Base UI includes prebuilt components with production-ready functionality, along
With Base UI, you can rapidly build on top of our foundational components using any styling solution you choose—no need to override any default style engine or theme.

:::info
Base UI is currently in beta.
Base UI is currently in alpha.

We're adding new components and features regularly, and you're welcome to contribute!

Expand Down
208 changes: 0 additions & 208 deletions docs/data/base/getting-started/quickstart/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,211 +38,3 @@ Please note that [react](https://www.npmjs.com/package/react) and [react-dom](ht
"react-dom": "^17.0.0 || ^18.0.0"
},
```

## 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](https://primer.style/components/button/) as a reference.

{{"demo": "Tutorial.js", "defaultCodeOpen": false, "hideToolbar": true}}

### 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](/base-ui/getting-started/usage/#components-vs-hooks) for details.

The code snippets below demonstrate the basic implementation of each:

#### Button component

```tsx
import * as React from 'react';
import { Button } from '@base_ui/react/Button';

export default function App() {
return <Button>Click Me</Button>;
}
```

#### useButton hook

```tsx
import * as React from 'react';
import { useButton } from '@base_ui/react/useButton';

export default function App() {
const { getRootProps } = useButton();
return (
<button type="button" {...getRootProps()}>
Click Me
</button>
);
}
```

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

{{"demo": "BaseButton.js", "defaultCodeOpen": false}}

You can use any styling method of your choice to make fully customizable components for your app. See [Customization](/base-ui/getting-started/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:

```css
/* styles.css */

.btn {
background-color: #1f883d;
/* the rest of the styles */
}
```

```tsx
/* App.js */

<Button className="btn">Create Repository</Button>
```

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

```css
/* To style the disabled state: */

.${buttonClasses.disabled} { /* ".base-Button-disabled" */
cursor: not-allowed;
}
```

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

{{"demo": "BaseButtonPlainCss.js", "defaultCodeOpen": false}}

### Styling with Tailwind CSS

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

```tsx
<Button className="bg-green-600 rounded-md py-1 px-4...">Create Repository</Button>
```

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

{{"demo": "BaseButtonTailwind.js", "hideToolbar": true, "bg": "inline"}}

### Styling with MUI System

[MUI System](https://mui.com/system/getting-started/) is a small set of CSS utilities 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](https://mui.com/system/styled/) 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`.

```tsx
import * as React from 'react';
import { ThemeProvider } from '@emotion/react';
import { styled } from '@mui/system';
import { Button } from '@base_ui/react/Button';

const theme = {
palette: {
primary: 'green',
text: '#fff',
},
};

const GitHubButton = styled(Button)(
({ theme }) => `
background-color: ${theme.palette.primary /* => 'green' */};
${/* ... the rest of the styles */}
`,
);

export default function App() {
return (
<ThemeProvider theme={theme}>
<GitHubButton>Create Repository</GitHubButton>
</ThemeProvider>
);
}

```

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](https://mui.com/material-ui/customization/default-theme/) documentation.

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

#### Button Component with MUI System

```tsx
import * as React from 'react';
import { Button } from '@base_ui/react/Button';
import { styled } from '@mui/system';

const GitHubButton = styled(Button)(
({ theme }) => `
background-color: ${theme.palette.mode === 'dark' ? '#238636' : '#1f883d'};
${/* ... the rest of the styles */}
`,
);

export default function App() {
return (
<GitHubButton>Create Repository</GitHubButton>
);
}
```

#### useButton hook with MUI System

```tsx
import * as React from 'react';
import { useButton } from '@base_ui/react/useButton';
import { styled } from '@mui/system';

const GitHubButton = styled('button')(
({ theme }) => `
background-color: ${theme.palette.mode === 'dark' ? '#238636' : '#1f883d'};
${/* ... the rest of the styles */}
`,
);

export default function App() {
const { getRootProps } = useButton(/* props*/);

return (
<GitHubButton type="button" {...getRootProps()}>
Create Repository
</GitHubButton>
);
}
```

### Using the sx prop

MUI System supports the [`sx` prop](https://mui.com/system/getting-started/the-sx-prop/), which provides a quick way to apply ad-hoc styles using theme-aware values to any component created with `styled`.

```tsx
const GitHubButton = styled(Button)(
({ theme }) => `
background-color: ${theme.palette.mode === 'dark' ? '#238636' : '#1f883d'};
margin: 0;
`,
);

export default function App() {
return (
<GitHubButton sx={{ m: 2 /* => margin: 16px */ }}>
Create Repository
</GitHubButton>
);
}
```

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

{{"demo": "BaseButtonMuiSystem.js", "defaultCodeOpen": false}}

Read the [MUI System Usage](https://mui.com/system/getting-started/usage/) doc for further details.
9 changes: 2 additions & 7 deletions docs/data/base/getting-started/support/support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,18 +67,13 @@ This includes issues introduced by external sources, like browser upgrades or ch

### Supported versions

- Base UI v5: ⚠️ Beta version.
- Base UI v4 🅧 Never existed.
- Base UI v3 🅧 Never existed.
- Base UI v2: 🅧 Never existed.
- Base UI v1: 🅧 Never existed.
- Base UI v0.x: 🅧 Never existed.
- Base UI v1: ⚠️ Alpha version.

## Community

### Social media

The Base UI community is active on both [X/Twitter](https://twitter.com/MaterialUI) and [LinkedIn](https://www.linkedin.com/company/mui/).
The Base UI community is active on both [X/Twitter](https://twitter.com/BaseUI) and [LinkedIn](https://www.linkedin.com/company/mui/).
These are great platforms to share what you're working on and connect with other developers.

### Discord
Expand Down
86 changes: 18 additions & 68 deletions docs/data/base/getting-started/usage/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,64 +18,40 @@ Base components are self-supporting and fully functional in isolation.

Each component has its own unique API, but all _non-utility_ components accept the following shared props:

### slots
### render

The `slots` prop is an object that lets you override any interior subcomponents—known as **slots**—of the base component itself.
The `render` prop lets you override the rendered element of the component.

:::info
Each component contains a root slot, and other appropriate slots based on the nature of the component.
For example, the Base UI Badge contains two slots:

- `root`: the container element that wraps the children.
- `badge`: the badge element itself.

:::

You can use the `slots` prop to override default slots with either custom components or HTML elements.

For example, the Base UI Badge component renders a `<span>` by default.
The code snippet below shows how to override this by assigning a `<div>` to the root slot:
For example, the Base UI Switch component renders a `<button>` by default.
The code snippet below shows how to use a custom component instead.

```jsx
<Badge slots={{ root: 'div' }} />
<Switch.Root render={<MyFancyButton />} />
```

### slotProps

The `slotProps` prop is an object that contains the props for all slots within a component.
You can use it to define additional custom props for a component's interior elements.
The custom component must forward a ref to its underlying DOM node and it must spread all the received props.

For example, the code snippet below shows how to add a custom CSS class to the badge slot of the Base UI Badge component:
The `render` prop comes in two variants: the element one (as shown above) and the function one.
Using a function gives you complete control over spreading props and allows you to render different content based on the component's state.

```jsx
<Badge slotProps={{ badge: { className: 'my-badge' } }} />
<Switch.Thumb
render={(props, internalState) => (
<span {...props}>
{internalState.checked ? <CheckedIcon /> : <UncheckedIcon />}
</span>
)}
/>
```

All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `slotProps.root`).
### className

These two examples are equivalent:
The `className` prop, in addition to accepting a string, can be defined as a function that takes a component state as an argument:

```jsx
<Badge id="badge1">
<Switch.Thumb className={(state) => (state.checked ? 'checked' : 'unchecked')} />
```

```jsx
<Badge slotProps={{ root: { id: 'badge1' } }}>
```

:::warning
If both `slotProps.root` and additional props have the same keys but different values, the `slotProps.root` props will take precedence.
This does not apply to classes or the `style` prop—they will be merged instead.
:::

### Best practices

If you are customizing a component like the [Button](/base-ui/react-button/) that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.

Overriding with `component` lets you apply the attributes of that element directly to the root.
For instance, if you replace the Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
If you did the same with `slots.root`, you would need to place this attribute on the `slotProps.root` object in order to avoid a TypeScript error.

## Components vs. hooks

Base UI includes two kinds of building blocks: **components** and **hooks**.
Expand All @@ -88,29 +64,3 @@ Many Base UI components are implemented with the help of [React hooks](https://
You can use components or hooks—or a combination of both—when building custom components.

In general, we recommend that you begin building with the component, and if you find that you are too limited by the customization options available, then consider refactoring your component to use the corresponding hook instead.

Each option has its own trade-offs:

### Components

#### Pros

- Usually require less code to implement
- Equipped with accessibility features by default

#### Cons

- Less control over the structure of the rendered HTML

### Hooks

#### Pros

- Complete control over rendered HTML structure

#### Cons

- Usually require more code to implement
- Extra steps necessary to make the resulting component accessible

Details on usage of hooks can be found in their corresponding component docs.
23 changes: 7 additions & 16 deletions docs/data/base/guides/next-js-app-router/next-js-app-router.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,9 +157,10 @@ To use Next.js with Base UI and styled-components or other CSS-in-JS solutions,

## Customization

### Using callbacks for slot props
### Using callbacks for render props

A common customization method in Base UI is to pass a callback to slots in `slotProps` in order to apply dynamic props. For example, you might want to change the background color by applying a different class when a Button is disabled:
A common customization method in Base UI is to pass a callback to the `render` or `className` props in order to apply dynamic values.
For example, you might want to change the background color by applying a different class when a Button is disabled:

```tsx
// page.tsx
Expand All @@ -169,25 +170,15 @@ export default function Page() {
<React.Fragment>
{/* Next.js won't render this button without 'use-client'*/}
<Button
slotProps={{
root: (ownerState: ButtonOwnerState) => ({
className: ownerState.disabled ? 'bg-gray-400' : 'bg-blue-400',
}),
}}
className={(ownerState: ButtonOwnerState) =>
ownerState.disabled ? 'bg-gray-400' : 'bg-blue-400'
}
>
Submit
</Button>

{/* Next.js can render this */}
<Button
slotProps={{
root: {
className: 'bg-gray-400',
},
}}
>
Return
</Button>
<Button className="bg-gray-400">Return</Button>
</React.Fragment>
);
}
Expand Down
Loading