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

[material-ui][docs] Revise the Accordion page #40284

Merged
merged 25 commits into from
Jan 5, 2024
Merged

[material-ui][docs] Revise the Accordion page #40284

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
19ba8f6
document complementary components
anle9650 Dec 23, 2023
474bac3
Update AccordionUsage.js
anle9650 Dec 23, 2023
c80c90d
Create AccordionUsage.tsx
anle9650 Dec 23, 2023
3ac58dc
Update AccordionUsage.js
anle9650 Dec 23, 2023
25b36c0
add expand icons
anle9650 Dec 23, 2023
643df79
Update accordion.md
anle9650 Dec 23, 2023
2a10fda
push in revised page + updated demos
danilo-leal Dec 25, 2023
802eb4a
fix hydration issue
anle9650 Dec 25, 2023
af951a4
remove basic-usage links
anle9650 Dec 25, 2023
c974946
Update accordion.md
anle9650 Dec 25, 2023
c7756d1
Update docs/data/material/components/accordion/accordion.md
anle9650 Dec 25, 2023
2f465e0
Update accordion.md
anle9650 Dec 25, 2023
e0a8ed3
Update docs/data/material/components/accordion/accordion.md
anle9650 Dec 25, 2023
b6cfe65
Update docs/data/material/components/accordion/accordion.md
anle9650 Dec 25, 2023
32ecb12
Update docs/data/material/components/accordion/accordion.md
anle9650 Dec 25, 2023
803a8ac
Update docs/data/material/components/accordion/accordion.md
anle9650 Dec 25, 2023
f921db5
Update docs/data/material/components/accordion/accordion.md
anle9650 Dec 25, 2023
d08d64b
Update docs/data/material/components/accordion/accordion.md
anle9650 Dec 25, 2023
cb12522
Accordion's -> Accordion
anle9650 Dec 25, 2023
43372ea
Sam's review round two
danilo-leal Dec 26, 2023
7c55cba
add in more demos for other avaialble props
danilo-leal Dec 26, 2023
39aacc0
expanded -> defaultExpanded
anle9650 Dec 26, 2023
c09ada3
fix typos
danilo-leal Jan 4, 2024
422cdf4
transition demo tweaks based on Diego's guidance
danilo-leal Jan 4, 2024
d814a5e
Expanded typos
DiegoAndai Jan 5, 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
57 changes: 57 additions & 0 deletions docs/data/material/components/accordion/AccordionUsage.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import * as React from 'react';
import Accordion from '@mui/material/Accordion';
import AccordionActions from '@mui/material/AccordionActions';
import AccordionSummary from '@mui/material/AccordionSummary';
import AccordionDetails from '@mui/material/AccordionDetails';
import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
import Button from '@mui/material/Button';

export default function AccordionUsage() {
return (
<div>
<Accordion>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel1-content"
id="panel1-header"
>
Accordion 1
</AccordionSummary>
<AccordionDetails>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
malesuada lacus ex, sit amet blandit leo lobortis eget.
</AccordionDetails>
</Accordion>
<Accordion>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel2-content"
id="panel2-header"
>
Accordion 2
</AccordionSummary>
<AccordionDetails>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
malesuada lacus ex, sit amet blandit leo lobortis eget.
</AccordionDetails>
</Accordion>
<Accordion expanded>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel3-content"
id="panel3-header"
>
Accordion Actions
</AccordionSummary>
<AccordionDetails>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
malesuada lacus ex, sit amet blandit leo lobortis eget.
</AccordionDetails>
<AccordionActions>
<Button>Cancel</Button>
<Button>Agree</Button>
</AccordionActions>
</Accordion>
</div>
);
}
57 changes: 57 additions & 0 deletions docs/data/material/components/accordion/AccordionUsage.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import * as React from 'react';
import Accordion from '@mui/material/Accordion';
import AccordionActions from '@mui/material/AccordionActions';
import AccordionSummary from '@mui/material/AccordionSummary';
import AccordionDetails from '@mui/material/AccordionDetails';
import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
import Button from '@mui/material/Button';

export default function AccordionUsage() {
return (
<div>
<Accordion>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel1-content"
id="panel1-header"
>
Accordion 1
</AccordionSummary>
<AccordionDetails>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
malesuada lacus ex, sit amet blandit leo lobortis eget.
</AccordionDetails>
</Accordion>
<Accordion>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel2-content"
id="panel2-header"
>
Accordion 2
</AccordionSummary>
<AccordionDetails>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
malesuada lacus ex, sit amet blandit leo lobortis eget.
</AccordionDetails>
</Accordion>
<Accordion expanded>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel3-content"
id="panel3-header"
>
Accordion Actions
</AccordionSummary>
<AccordionDetails>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
malesuada lacus ex, sit amet blandit leo lobortis eget.
</AccordionDetails>
<AccordionActions>
<Button>Cancel</Button>
<Button>Agree</Button>
</AccordionActions>
</Accordion>
</div>
);
}
14 changes: 7 additions & 7 deletions ...al/components/accordion/BasicAccordion.js → ...components/accordion/DisabledAccordion.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ import AccordionDetails from '@mui/material/AccordionDetails';
import Typography from '@mui/material/Typography';
import ExpandMoreIcon from '@mui/icons-material/ExpandMore';

export default function BasicAccordion() {
export default function DisabledAccordion() {
return (
<div>
<Accordion>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel1a-content"
id="panel1a-header"
aria-controls="panel1-content"
id="panel1-header"
>
<Typography>Accordion 1</Typography>
</AccordionSummary>
Expand All @@ -26,8 +26,8 @@ export default function BasicAccordion() {
<Accordion>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel2a-content"
id="panel2a-header"
aria-controls="panel2-content"
id="panel2-header"
>
<Typography>Accordion 2</Typography>
</AccordionSummary>
Expand All @@ -41,8 +41,8 @@ export default function BasicAccordion() {
<Accordion disabled>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel3a-content"
id="panel3a-header"
aria-controls="panel3-content"
id="panel3-header"
>
<Typography>Disabled Accordion</Typography>
</AccordionSummary>
Expand Down
14 changes: 7 additions & 7 deletions ...l/components/accordion/BasicAccordion.tsx → ...omponents/accordion/DisabledAccordion.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ import AccordionDetails from '@mui/material/AccordionDetails';
import Typography from '@mui/material/Typography';
import ExpandMoreIcon from '@mui/icons-material/ExpandMore';

export default function BasicAccordion() {
export default function DisabledAccordion() {
return (
<div>
<Accordion>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel1a-content"
id="panel1a-header"
aria-controls="panel1-content"
id="panel1-header"
>
<Typography>Accordion 1</Typography>
</AccordionSummary>
Expand All @@ -26,8 +26,8 @@ export default function BasicAccordion() {
<Accordion>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel2a-content"
id="panel2a-header"
aria-controls="panel2-content"
id="panel2-header"
>
<Typography>Accordion 2</Typography>
</AccordionSummary>
Expand All @@ -41,8 +41,8 @@ export default function BasicAccordion() {
<Accordion disabled>
<AccordionSummary
expandIcon={<ExpandMoreIcon />}
aria-controls="panel3a-content"
id="panel3a-header"
aria-controls="panel3-content"
id="panel3-header"
>
<Typography>Disabled Accordion</Typography>
</AccordionSummary>
Expand Down
80 changes: 61 additions & 19 deletions docs/data/material/components/accordion/accordion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,37 @@

<p class="description">The accordion component allows the user to show and hide sections of related content on a page.</p>
danilo-leal marked this conversation as resolved.
Show resolved Hide resolved

An accordion is a lightweight container that may either be used standalone, or be connected to a larger surface, such as a card.

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

## Introduction

The Material UI Accordion component includes several complementary utility components to handle various use cases:

- [Accordion](#basic-usage): the wrapper for grouping related components.
anle9650 marked this conversation as resolved.
Show resolved Hide resolved
- [Accordion Summary](#basic-usage): the wrapper for the Accordion's header, which expands or collapses the content when clicked.
anle9650 marked this conversation as resolved.
Show resolved Hide resolved
- [Accordion Details](#basic-usage): the wrapper for Accordion's content.
anle9650 marked this conversation as resolved.
Show resolved Hide resolved
- [Accordion Actions](#basic-usage): an optional wrapper that groups a set of buttons.

{{"demo": "AccordionUsage.js", "bg": true}}

:::info
This component is no longer documented in the [Material Design guidelines](https://m2.material.io/), but Material UI will continue to support it.
:::

## Basic accordion
## Basics

{{"demo": "BasicAccordion.js", "bg": true}}
```jsx
import Accordion from '@mui/material/Accordion';
import AccordionDetails from '@mui/material/AccordionDetails';
import AccordionSummary from '@mui/material/AccordionSummary';
```

## Controlled accordion
### Controlled accordion
anle9650 marked this conversation as resolved.
Show resolved Hide resolved

The Accordion component can be controlled or uncontrolled.

{{"demo": "ControlledAccordions.js", "bg": true}}

:::info

- A component is **controlled** when it's managed by its parent using props.
Expand All @@ -35,34 +50,61 @@
Learn more about controlled and uncontrolled components in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
:::

{{"demo": "ControlledAccordions.js", "bg": true}}
### Disabled item

Use the disabled prop on the `Accordion` component to disable interaction and focus.
anle9650 marked this conversation as resolved.
Show resolved Hide resolved

{{"demo": "DisabledAccordion.js", "bg": true}}

## Customization

Here is an example of customizing the component.
You can learn more about this in the [overrides documentation page](/material-ui/customization/how-to-customize/).
### One opened item per time
anle9650 marked this conversation as resolved.
Show resolved Hide resolved

Use the `expanded` prop, together with React's `useState` to set only one opened item per time.
anle9650 marked this conversation as resolved.
Show resolved Hide resolved
The demo below also shows a bit of visual customziation.

{{"demo": "CustomizedAccordions.js"}}

## Performance

The content of Accordions is mounted by default even if the accordion is not expanded.
The Accordion's content is mounted by default even if it's not expanded.
This default behavior has server-side rendering and SEO in mind.
If you render expensive component trees inside your accordion details or simply render many
accordions it might be a good idea to change this default behavior by enabling the
`unmountOnExit` in `TransitionProps`:

However, if you render the Accordion Details with a big component tree inside it, or if you have many Accordions, we recommend changing this behavior by turning `unmountOnExit` on inside the `TransitionProps` prop:

Check warning on line 73 in docs/data/material/components/accordion/accordion.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.We] Try to avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Google.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "docs/data/material/components/accordion/accordion.md", "range": {"start": {"line": 73, "column": 115}}}, "severity": "WARNING"}
anle9650 marked this conversation as resolved.
Show resolved Hide resolved

```jsx
<Accordion TransitionProps={{ unmountOnExit: true }} />
```

As with any performance optimization this is not a silver bullet.
Be sure to identify bottlenecks first and then try out these optimization strategies.

## Accessibility

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
For an optimal accessibility, based on the [WAI-ARIA guidelines](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/), set an `id` and `aria-controls` on the Accordion Summary component.
anle9650 marked this conversation as resolved.
Show resolved Hide resolved
The Accordion component will then derive the necessary `aria-labelledby` and `id` from its content.

Check warning on line 82 in docs/data/material/components/accordion/accordion.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Will] Avoid using 'will'.

Raw Output:
{"message": "[Google.Will] Avoid using 'will'.", "location": {"path": "docs/data/material/components/accordion/accordion.md", "range": {"start": {"line": 82, "column": 25}}}, "severity": "WARNING"}
anle9650 marked this conversation as resolved.
Show resolved Hide resolved

For optimal accessibility we recommend setting `id` and `aria-controls` on the
`AccordionSummary`. The `Accordion` will derive the necessary `aria-labelledby`
and `id` for the content region of the accordion.
```jsx
<Accordion>
<AccordionSummary id="panel-header" aria-controls="panel-content">
Header
</AccordionSummary>
<AccordionDetails>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
</AccordionDetails>
</Accordion>
```

## Anatomy

The Accordion component is composed of a root <div> that houses interior elements like the Accordion Summary and other optional components (such as buttons or decorators).

```jsx
<div class="MuiAccordion-root">
<div class="MuiButtonBase-root MuiAccordionSummary-root" role="button" aria-expanded="">
<!-- Accordion header button goes here -->
</div>
<div class="MuiAccordion-region" role="region">
<div class="MuiAccordionDetails-root">
<!-- Accordion content goes here -->
</div>
</div>
</div>
```