Accordion
Questions that open to show their answers, so long help and settings pages stay short. People open only what they need.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add accordionAlso works with shadcn:
npx shadcn@latest add @ritla/accordionDependencies it brings
@base-ui/react@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { Accordion, AccordionItem } from "@/components/ui/accordion";<Accordion divider> <AccordionItem value="refund" question="How long does a refund take?"> Most refunds reach your account within five working days. </AccordionItem></Accordion>Examples
One at a time
multiple={false}: opening one section closes the other. Fine for settings; in a FAQ let several stay open, since people compare answers.
Mobile, icon at the start
breakpoint="mobile" sets body-16 questions and an 8px gap; iconPosition="start" puts the icon before the question. Both are set on the stack, so no item differs. The default, auto, is Mobile below md and Desktop above.
Opened from a link
Start closed and open the item a link points to by controlling value. Find-in-page also opens a closed answer that holds the text: search for IBAN.
API reference
Accordion
| Prop | Type | Default | Description |
|---|---|---|---|
multiple | boolean | true | Several items open at once; false for one. |
defaultValue | string[] | None | Items open at first. |
value / onValueChange | string[] | None | Controls which items are open. |
breakpoint | "auto" | "desktop" | "mobile" | "auto" | Figma's Breakpoint, for the whole stack. |
iconPosition | "end" | "start" | "end" | Figma's Icon position, for the whole stack. |
divider | boolean | false | Figma's Divider: a line above each item. |
AccordionItem
| Prop | Type | Default | Description |
|---|---|---|---|
question | ReactNode | None | Figma's Question: a button inside a heading. |
children | ReactNode | None | Figma's Answer: a short paragraph, a list or a link. |
value | string | None | The item's key in value. |
id | string | None | For # links to the item. |
icon | boolean | true | Figma's Icon: the plus / minus icon. |
headingLevel | 2 | 3 | 4 | 5 | 6 | 3 | The heading level around the question. |
disabled | boolean | false | Stops it opening or closing. |
Usage guidelines
An accordion hides detail that only some people need. Accordion, Collapsible or FAQ section, writing questions and answers, opening and closing, what fits in a panel, how it mirrors in Arabic, and the checks before handoff.
1. Accordion, Collapsible or FAQ section
Accordions hide detail that only some people need. If everyone needs the content, show it. Pick the part by how many panels there are and where they sit.
| You need to | Use | Why |
|---|---|---|
| Answer many questions in a stack, opened one by one | Accordion item | People scan the questions and open only theirs. |
| Hide one block of optional detail, such as fees | Collapsible | A single panel with a summary line that stays visible. |
| Add a full FAQ block to a marketing page | FAQ section, Accordion types | A ready section with heading, questions and a contact link. |
| Show five or fewer short answers | FAQ section, Simple types | Short answers read faster when they are all open. |
| Switch between views of equal weight | Tabs | Only one view shows, and every view has a name. |
2. Writing questions and answers
The question is the only thing people see before they open an item, so write it the way people ask it. Answer in the first sentence, then add detail.
Questions people ask
A wallet help page.
Do
- Write questions in the words people use: How long does a transfer take?
- Answer the question in the first sentence.
- Keep answers to a short paragraph or a short list.
- Order questions by how often people ask them.
Don't
- Use topic labels such as General or Other as headers.
- Start an answer by repeating the question.
- Hide a long article inside one item; link to it.
3. Opening and closing
The whole header row opens and closes the item, not only the icon. The icon shows the state: plus when closed, minus when open. Start with every item closed, unless people arrive from a link to a specific answer.
Do
- Make the whole header row the trigger.
- Start closed; open the item a link points to.
- Let people open several items at once in a FAQ.
- Keep the icon at the end, on the same side in every item.
- Keep open items open when people come back to the page.
Don't
- Make only the icon clickable.
- Close other items on their own in a FAQ; people compare answers.
- Mix Icon position Start and End in one stack.
- Animate the open and close for longer than
duration/moderate.
4. What fits in a panel
A panel holds a short answer: a paragraph, a short list or a link to more. Keep required content and form fields out of accordions; people skip closed panels.
Do
- Put a paragraph, a short list or a link in a panel.
- Link to a full article when the answer is long.
- Use Divider=True between items in a stack.
Don't
- Nest an accordion inside an accordion.
- Hide required form fields or legal terms people must read.
- Put the only way to finish a task inside a closed panel.
5. Arabic and RTL
Use the RTL variant in Arabic. Questions and answers align right and the icon moves to the inline end, which is the left. The plus and minus icons are symmetric, so nothing inside them mirrors. Amounts and times in answers still read left to right.
Icon at the inline end
The same help page in Arabic.
Before handoff
- Questions are written the way people ask them.
- The default open state is marked, and deep links open their item.
- Content everyone needs is not hidden.
- Arabic stacks use the RTL variant.
- Mobile uses Breakpoint=Mobile.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Tab | From question to question, and into the links of an open answer. |
| EnterSpace | Opens or closes the question; focus stays on it. |
ARIA
- Each question is a button inside a heading (
h3by default), so screen readers jump between questions and hear whether each is open. - The button has
aria-expandedandaria-controlspointing at the answer region. The plus / minus icon is decorative. - The whole question row is the button, with a touch area of at least 48px.
- Opening and closing take 200ms, and are instant under reduced motion.
Do
- The header button sits inside a heading at the right level.
aria-expandedon the button andaria-controlspointing at its panel.- Enter and Space toggle the item, and focus stays on the header.
- A header row at least 48 px tall.
Don't
- Headers made of plain text with a click handler.
- The icon alone to show the state.
Arabic and RTL notes
Mirrors
- The question and answer start on the right, and the icon sits at the inline end: the left.
iconPosition="start"puts the icon on the right in Arabic.
Does not mirror
- The plus and minus icons are symmetric, so nothing in them mirrors.
- Numerals
- Amounts and times in answers read left to right; format numbers with
formatNumber. - Arabic typography
- Questions
body-18Medium (Mobilebody-16), answersbody-16. Arabic lines are taller, so rows grow rather than clip. - Mixed-direction text
- Write Arabic questions the way people ask them in Arabic, not word-for-word translations.
Do
- The RTL variant for every item in an Arabic stack.
- The icon at the inline end, which is the left in Arabic.
- Write Arabic questions the way people ask them in Arabic.
- Keep amounts, times and codes left to right inside answers.
Don't
- Arabic text in the English variant.
- Translate English questions word for word.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- text-align: left explicitly set on majority-Arabic text
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)