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

[docs][base-ui] Revise the structure of the Component docs #38529

Merged
merged 1 commit into from
Aug 22, 2023
Merged

[docs][base-ui] Revise the structure of the Component docs #38529

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
52 changes: 11 additions & 41 deletions docs/data/base/components/autocomplete/autocomplete.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,18 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/

# Autocomplete

<p class="description">The Autocomplete component is a text input enhanced by a panel of suggested options.</p>
<p class="description">An autocomplete component is a text input enhanced by a panel of suggested options.</p>

{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}

{{"component": "modules/components/ComponentPageTabs.js"}}

## Introduction

The autocomplete component is an enhanced text input that shows a list of suggested options as users type and lets them select an option from the list. It implements the WAI-ARIA Combobox pattern, and is typically used to assist users in completing form inputs or search queries faster.
An autocomplete component is an enhanced text input that shows a list of suggested options as users type, and lets them select an option from the list.

Base UI provides the `useAutocomplete` hook for building a custom Autocomplete.
It implements the WAI-ARIA Combobox pattern, and is typically used to assist users in completing form inputs or search queries faster.

{{"demo": "AutocompleteIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}

Expand All @@ -30,51 +33,18 @@ To learn more about implementing a custom Autocomplete, you can explore the [`us

:::

## Usage
## Hook

After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this hook as follows:
### Usage

```jsx
import { useAutocomplete } from '@mui/base/useAutocomplete';

export default function App() {
const {
getRootProps,
getInputProps,
getListboxProps,
getOptionProps,
groupedOptions,
} = useAutocomplete({
options: [
{ label: 'The Dark Knight', year: 2008 },
{ label: '12 Angry Men', year: 1957 },
{ label: "Schindler's List", year: 1993 },
],
getOptionLabel: (option) => option.label,
});

return (
<React.Fragment>
<div {...getRootProps()}>
<input {...getInputProps()} />
</div>
{groupedOptions.length > 0 && (
<ul {...getListboxProps()}>
{groupedOptions.map((option, index) => (
<li {...getOptionProps({ option, index })}>{option.label}</li>
))}
</ul>
)}
</React.Fragment>
);
}
```

## Basics

The useAutocomplete hook requires a list of `options` to be displayed when the textbox receives focus. The value must be chosen from a predefined set of values.
The `useAutocomplete` hook requires a list of `options` to be displayed when the textbox receives focus.
The value must be chosen from a predefined set of values.

The following demo shows how to create a simple combobox, apply some styling, and write the selected value to a state variable using the `onChange` prop:
The following demo shows how to create a simple combobox, apply styles, and write the selected value to a state variable using the `onChange` prop:

{{"demo": "UseAutocomplete.js"}}

Expand Down Expand Up @@ -113,7 +83,7 @@ const {

### Controlled states

The useAutocomplete hook has two states that can be controlled:
The `useAutocomplete` hook has two states that can be controlled:

1. the "value" state with the `value`/`onChange` props combination. This state represents the value selected by the user, for instance when pressing <kbd class="key">Enter</kbd>.
2. the "input value" state with the `inputValue`/`onInputChange` props combination. This state represents the value displayed in the textbox.
Expand Down
13 changes: 0 additions & 13 deletions docs/data/base/components/slider/slider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,23 +28,10 @@ Sliders are ideal for interface controls that benefit from a visual representati

### Usage

After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:

```jsx
import { Slider } from '@mui/base/Slider';

export default function MyApp() {
return <Slider />;
}
```

### Basics

The following demo shows how to create and style two basic sliders.
Notice that both are set to a default value of 10 with the `defaultValue` prop, and the second slider cannot be adjusted due to the `disabled` prop:

{{"demo": "UnstyledSliderBasic", "defaultCodeOpen": false}}

### Anatomy

The Slider component is composed of a root `<span>` that houses several interior `<span>` elements:
Expand Down
16 changes: 2 additions & 14 deletions docs/data/base/components/switch/switch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,22 +25,10 @@ The Switch component provides users with a switch for toggling between two mutua

### Usage

After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:

```jsx
import { Switch } from '@mui/base/Switch';

export default function MyApp() {
return <Switch />;
}
```

### Basics

The following demo shows how to assign styles and props to the Switch component:

{{"demo": "UnstyledSwitchIntroduction"}}

### Anatomy

The Switch component is composed of a root `<span>` that houses three interior slots—a track, a thumb, and an input:
Expand Down Expand Up @@ -96,7 +84,7 @@ import { useSwitch } from '@mui/base/useSwitch';
The `useSwitch` hook lets you apply the functionality of a switch to a fully custom component.
It returns props to be placed on the custom component, along with fields representing the component's internal state.

Hooks _do not_ support [slot props](#slot-props), but they do support [customization props](#customization).
Hooks _do not_ support [slot props](#custom-structure), but they do support [customization props](#customization).

:::info
Hooks give you the most room for customization, but require more work to implement.
Expand All @@ -115,4 +103,4 @@ You may not need to use hooks unless you find that you're limited by the customi

## Accessibility

To make the switch component accessible, you should ensure that the corresponding labels reflect the current state of the switch.
To make the Switch component accessible, you should ensure that the corresponding labels reflect the Switch's current state.
17 changes: 0 additions & 17 deletions docs/data/base/components/tabs/tabs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,30 +30,13 @@ Tabs are implemented using a collection of related components:

### Usage

After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component collection using the following basic elements:

```jsx
import { Tab } from '@mui/base/Tab';
import { TabsList } from '@mui/base/TabsList';
import { TabPanel } from '@mui/base/TabPanel';
import { Tabs } from '@mui/base/Tabs';

export default function MyApp() {
return (
<Tabs>
<TabsList>
<Tab>{/* tab one */}</Tab>
<Tab>{/* tab two */}</Tab>
</TabsList>
<TabPanel>{/* panel one */}</TabPanel>
<TabPanel>{/* panel two */}</TabPanel>
</Tabs>
);
}
```

### Basics

By default, Tab components and their corresponding panels are **zero-indexed** (i.e. the first tab has a `value` of `0`, then `1`, `2`, etc.).
Clicking on a given Tab opens the panel with the same `value`, which corresponds to the order in which each component is nested within its container.

Expand Down