Skip to content

Commit

Permalink
[joy-ui][docs] Revise the Lists page (mui#36324)
Browse files Browse the repository at this point in the history 
Signed-off-by: Siriwat K <[email protected]>
Signed-off-by: Danilo Leal <[email protected]>
Co-authored-by: siriwatknp <[email protected]>
Co-authored-by: Sam Sycamore <[email protected]>
Co-authored-by: Danilo Leal <[email protected]>
  • Loading branch information
@LadyBluenotes @siriwatknp
@samuelsycamore @danilo-leal
4 people authored Sep 5, 2023
1 parent e9bd183 commit ab1c307
Show file tree
Hide file tree
Showing 5 changed files with 142 additions and 94 deletions.
2 changes: 1 addition & 1 deletion docs/data/joy/components/autocomplete/autocomplete.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ You could also display a dialog when the user wants to add a new value.
{{"demo": "FreeSoloCreateOptionDialog.js"}}

:::info
The `AutocompleteOption` uses the same styles and variables as [`ListItemButton`](/joy-ui/react-list/#actionable), so that you get the same customization experience.
The `AutocompleteOption` uses the same styles and variables as [`ListItemButton`](/joy-ui/react-list/#interactive-list-items), so that you get the same customization experience.
:::

### Validation
Expand Down
228 changes: 138 additions & 90 deletions docs/data/joy/components/list/list.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,157 +7,174 @@ githubLabel: 'component: list'

# Lists

<p class="description">Lists are continuous, vertical indexes of text or images.</p>
<p class="description">Lists are organizational tools that enhance the readability and organization of content.</p>

## Introduction

Joy UI provides four list-related components:
Lists present information in a concise, easy-to-follow format through a continuous, vertical index of text or images.

- [`List`](#basic-usage): A wrapper for list items (defaulting as `ul`).
- [`ListItem`](#basic-usage): A common list item (default as `li`).
- [`ListItemButton`](#actionable): An action element to be used inside a list item.
- [`ListItemDecorator`](#decorator): A decorator of a list item, usually used to display an icon.
- [`ListItemContent`](#ellipsis-content): A container inside a list item, used to display text content.
- [`ListDivider`](#divider): A separator between list items.
- [`ListSubheader`](#nested-list): A label for a nested list.
Joy UI Lists are implemented using a collection of related components:

{{"demo": "ListUsage.js", "hideToolbar": true, "bg": "gradient"}}
- [List](#basics) - a wrapper for list items. Renders as a `<ul>` by default.
- [List Item](#basics) - a common list item. Renders as an `<li>` by default.
- [List Item Button](#interactive-list-items) - an action element to be used inside a list item.
- [List Item Decorator](#decorators) - a decorator of a list item, usually used to display an icon.
- [List Item Content](#ellipsis-content) - a container inside a list item, used to display text content.
- [List Divider](#divider) - a separator between list items.
- [List Subheader](#nested-list) - a label for a nested list.

## Component
{{"demo": "ListUsage.js", "hideToolbar": true, "bg": "gradient"}}

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

```jsx
import List from '@mui/joy/List';
import ListItem from '@mui/joy/ListItem';

export default function MyApp() {
return (
<List aria-label="basic-list">
<ListItem>Hello, world!</ListItem>
<ListItem>Bye bye, world!</ListItem>
</List>
);
}
```

### Basic usage
## Customization

Use the `List` and `ListItem` components to create a basic, non-interactive, list.
Make sure to use a meaningful name that describe the content of the list in the `aria-labelledby` prop.
### Variants

{{"demo": "BasicList.js"}}
The List component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft`, `outlined`, and `plain`.

### Sizes

Use the `size` prop to control font-size and general list density.
The List component comes in three sizes: `sm`, `md`, and `lg`.
The size of the List determines its font size and density.

{{"demo": "SizesList.js"}}

:::info
To learn how to add more sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
:::

### Decorator
### Colors

Use the `ListItemDecorator` component to add supporting icons or elements to the list item.
Every palette included in the theme is available via the `color` prop.

It comes with a minimum set width that you can adjust via the `--ListItemDecorator-size` CSS variable within the `List` component.
### Decorators

```jsx
import ListItemDecorator from '@mui/joy/ListItemDecorator';
```

Use the List Item Decorator component to add supporting icons or elements to the list item.

{{"demo": "DecoratedList.js"}}

:::info
The List Item Decorator comes with a minimum set width that can be adjusted using the `--list-decorator-size` CSS variable within the List component.
:::

### Horizontal list

Use the `orientation="horizontal"` prop on the List component to display the List horizontally.

{{"demo": "HorizontalList.js"}}

:::warning
While nested lists will not work in a horizontal direction, you can create a custom pop-up component to achieve a similar effect (see the [Navigation menu](#navigation-menu) example).
:::

### Semantic elements

Use the `component` prop to control which HTML tag is rendered.

```js
<List component="ol">
```

The example below renders the List component as an HTML `<nav>` element.

{{"demo": "NavList.js"}}

:::info
The List Item component is optional in this case.
If used, it will automatically change the semantic element from the default `<li>` to `<div>`.
:::

### Ellipsis content

When dealing with long content, use the `ListItemComponent` together with `<Typography noWrap>` to show ellipsis.
```jsx
import ListItemContent from '@mui/joy/ListItemContent';
```

When working with longer content in a List, you can use the List Item Content component in combination with `<Typography noWrap />` to display an ellipsis when the content exceeds the available space.
This can help to keep the List Items visually consistent and prevent text from overflowing outside of the List Item's container.

{{"demo": "EllipsisList.js"}}

### Divider

The `ListDivider` component comes with four `inset` patterns:
```jsx
import ListDivider from '@mui/joy/ListDivider';
```

The List Divider component comes with four `inset` patterns:

- Default (without providing the `inset` prop): stretches from edge to edge of the list.
- `inset="gutter"`: from the start of the decorator to the end of the content.
- `inset="startDecorator"`: from the start of the decorator to the end of the list.
- `inset="startContent"`: from the start of the content to the end of the list.
- Default (no `inset` prop provided): stretches form one edge of the List to the other.
- `inset="gutter"`: from the start of List Item Decorator to the end of the content.
- `inset="startDecorator"`: from the start of List Item Decorator to the end of the edge of the container.
- `inset="startContent"`: from the start of the content to the edge of the container.

{{"demo": "DividedList.js"}}

For horizontal list, only `inset="gutter"` works on list divider.
If you're using a horizontal list, only `inset="gutter"` will work as the list divider.

{{"demo": "HorizontalDividedList.js"}}

### Sticky item

To have a sticky list item, use a `List` as a child of the `Sheet` component.
Then, on the item you wish to stick, add the `sticky` prop.
Use the List component as a child of the Sheet component to create "sticky" items.
On the item you wish to stick, you can then add the `sticky` prop.

The `Sheet` component automatically adjusts the `sticky` list item to have the same background so that the content does not overflow when scroll.
It works by default on both light and dark modes.
The Sheet component automatically adjusts the `sticky` list item to have the same background so that content does not overflow when scrolling.

{{"demo": "StickyList.js"}}

:::info
By default, this works on both light and dark modes.
:::

### Nested list

Use the `nested` prop, within the `ListItem` component, to create a nested list.
Note that layout and spacing of the nested list remain intact, as if it isn't nested.
```jsx
import ListSubheader from '@mui/joy/ListSubheader';
```

The nested list inherits the list `size` and a few other CSS variables, such as `--List-radius` and `--ListItem-radius` from the root `List` component to adjust the design consistently.
You can create a nested list using the `nested` prop on a List Item.
This enables you to add a List Subheader as well as a new List component as children of the List Item.
The nested List will inherit its `size` as well as other CSS variables like `--List-radius` and `--ListItem-radius` from the root List component to keep the design consistent.
The layout and spacing of the nested List will remain independent.

{{"demo": "NestedList.js"}}

:::info
By default, nested lists stick to the left of the root list.
To add spacing to the start of the nested list, use `--List-nestedInsetStart: ${value}`:
Nested lists will stick to the left of the root list, by default. If you need to add spacing to the start of the nested list you can use `--List-nestedInsetStart: ${value}`.

```js
<List sx={{ '--List-nestedInsetStart': '1rem' }}> {/* This is the root List */}
```

:::

### Horizontal list

To show a list in a horizontal direction, use the `orientation="horizontal"` prop on the `List` component.

:::warning
Nested lists don't work in the horizontal direction.
To do that, create a custom pop-up component instead (see the [Navigation menu](#navigation-menu) example).
:::

{{"demo": "HorizontalList.js"}}

### Changing the semantic element

To control which HTML tag should be rendered in a given, one-off, situation, use the `component` prop.
### Interactive list items

```js
<List component="ol">
```jsx
import ListItemButton from '@mui/joy/ListItemButton';
```

#### Non-list

In the example below, we're rendering a `List` as a HTML `<nav>` element.

:::info
**Tip**: The `ListItem` component is optional in this case－if used, it will change the semantic element from the default `li` to `div` automatically.
:::

{{"demo": "NavList.js"}}

### Actionable

To make a list item interactive, use `ListItemButton` **inside** a `ListItem`.
To make a List Item interactive, you can use List Item Button inside a List Item.

{{"demo": "ActionableList.js"}}

### Secondary action

To add a secondary action to the `ListItemButton`, wrap it in a `ListItem` component and then add the desired start or end action elements to it.
To add a secondary action to the List Item Button, wrap it in a List Item component and then add the desired start or end action elements to it.

{{"demo": "SecondaryList.js"}}

The `ListItemButton` and the secondary action render as siblings, that way, the semantic rendered element is appropriately adjusted.
:::info
The List Item Button and the secondary action render as siblings so that the rendered semantic element is appropriately adjusted.

```js
<ul> {/* List */}
Expand All @@ -166,22 +183,23 @@ The `ListItemButton` and the secondary action render as siblings, that way, the
<button> {/* IconButton */}
```

:::

### Selected

Use the `selected` prop to signal whether a `ListItemButton` is selected or not.
It applies `color="primary"` of the active variant to visually communicate the selected state.
Use the `selected` prop on the List Item Button component to indicate whether or not an item is currently selected.
When the item is selected, it applies `color="primary"` and a few extra styles—like font weight—to visually communicate the selected state.

{{"demo": "SelectedList.js"}}

:::info
A selected `ListItemButton` does not apply `:hover` and `:active` global variant styles.
A selected List Item Button does not apply `:hover` and `:active` global variant styles.
:::

{{"demo": "SelectedList.js"}}

## CSS variables playground

Play around with all the CSS variables available in the list component to see how the design changes.

You can use those to customize the component on both the `sx` prop and the theme.
Play around with the CSS variables available to the List components to see how the design changes.
You can use these to customize the components with both the `sx` prop and the theme.

{{"demo": "ListVariables.js", "hideToolbar": true, "bg": "gradient"}}

Expand All @@ -195,14 +213,14 @@ This example uses nested lists to split the settings into groups.

### Gmail navigation

Inspired by Gmail's web sidenav.
Inspired by Gmail's desktop navigation bar.

{{"demo": "ExampleGmailList.js"}}

### Collapsible list

Inspired by [Gatsby's documentation](https://www.gatsbyjs.com/docs) sidenav.
This example uses the start action (a prop of `ListItem`) prop to create a collapsible button.
Inspired by the [Gatsby documentation](https://www.gatsbyjs.com/docs) navbar.
This example uses the `startAction` prop to create a collapsible button.

{{"demo": "ExampleCollapsibleList.js"}}

Expand All @@ -214,3 +232,33 @@ This example uses a combination of horizontal and vertical lists to form the nav
It also supports keyboard navigation, inspired by the [Roving UX](https://github.com/argyleink/roving-ux) technique.

{{"demo": "ExampleNavigationMenu.js"}}

## Accessibility

To ensure that your List is accessible, here are some factors you should consider:

- Use the appropriate HTML semantic element for the list (eg. `ol` or `ul`), to ensure that assistive technologies can correctly interpret the list structure.
- Make sure to use a meaningful name that describes the content of the list in the `aria-labelledby` prop.
- Use `role` attributes to provide additional information about the purpose of the list and its items.
For example, use `role="list"` for the list and `role="listitem"` for each list item.

## Anatomy

The List component is composed of a root `<ul>` element with one or more child `<li>` elements rendered by the List Item component.
All components nested inside the List Item are optional.
The [List Divider](#divider) (when present) renders an `<li>` with `role="separator"`, while the [List Subheader](#nested-list) renders a `<div>`.

```html
<ul class="MuiList-root">
<li class="MuiListItem-root">
<div class="MuiListItemButton-root" role="button">
<span class="MuiListItemDecorator-root">
<!-- Icon for List Item Decorator -->
</span>
<div class="MuiListItemContent-root">
<!-- List Item content -->
</div>
</div>
</li>
</ul>
```
2 changes: 1 addition & 1 deletion docs/data/joy/components/menu/menu-pt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ When specifying a size for the `Menu` component, menu items inside of it will in

Use the `selected` prop to signal whether a `MenuItem` is selected or not.

The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#selected).
The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#interactive-list-items).

{{"demo": "SelectedMenu.js"}}

Expand Down
2 changes: 1 addition & 1 deletion docs/data/joy/components/menu/menu-zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ When specifying a size for the `Menu` component, menu items inside of it will in

Use the `selected` prop to signal whether a `MenuItem` is selected or not.

The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#selected).
The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#interactive-list-items).

{{"demo": "SelectedMenu.js"}}

Expand Down
2 changes: 1 addition & 1 deletion docs/data/joy/components/menu/menu.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ To learn how to add more sizes to the component, check out [Themed components—

Use the `selected` prop to signal whether a `MenuItem` is selected or not.

The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#selected).
The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#interactive-list-items).

{{"demo": "SelectedMenu.js"}}

Expand Down

0 comments on commit ab1c307

Please sign in to comment.