Accordion
# Features
- Full keyboard navigation support for accessibility.
- Ability to expand one or multiple items.
- Support for disabled items.
# Anatomy
Typically, an accordion consists of:
- Root: The root container for the accordion.
- Item: The container for each accordion item. Each accordion item consists of:
- Trigger: The trigger for the accordion item.
- Content: The content area that is revealed when the trigger is clicked.
<script>
import { createAccordion } from '@grail-ui/svelte';
const { useAccordion, itemAttrs, triggerAttrs, contentAttrs } = createAccordion();
const data = [
{ key: "item-1", title: "Button 1", content: "Content for one." },
{ key: "item-2", title: "Button 2", content: "Content for two." },
{ key: "item-3", title: "Button 3", content: "Content for three." },
];
</script>
<ul use:useAccordion>
{#each data as item}
<li {...$itemAttrs(item.key)}>
<button {...$triggerAttrs(item.key)}>{item.title}</button>
<div {...$contentAttrs(item.key)}>{item.content}</div>
</li>
{/each}
</ul>
# Examples
# Multiple items open at the same time
Pass multiple: true
to enable opening multiple items at once.
createAccordion({
multiple: true,
})
# Expanded by default
Use the value
prop to define the open item by default.
createAccordion({
value: ['item-1'],
multiple: true,
})
# Disabling specific items
To disable specific accordion items, pass their respective keys to the factory function.
When an accordion item is disabled, it is skipped from keyboard navigation and can't be interacted with.
createAccordion({
disabled: ['item-1'],
})
You can also disable the entire accordion by passing disabled: true
.
createAccordion({
disabled: true,
})
You can always modify the disabled items using the returned disabled
writable store.
# Listening to state changes
Pass onValueChange
to perform some custom logic when the expanded state is changed.
This callback is invoked with either the key of the accordion or an array of keys based on the value
of
multiple
.
createAccordion({
onValueChange(value) {
console.log(value);
},
})
# Value type safety
By default createAccordion
will accept any string
as a valid value.
If you want to narrow it down to specific values, you can use a generic like this
createAccordion<'a' | 'b' | 'c'>()
An expanded example would look like this:
type AccordionKey = 'accessibility' | 'flexibility' | 'animations';
const {...} = createAccordion<AccordionKey>({ value: 'animations' });
const data: { key: AccordionKey, ... }[] = [
...
]
# Accessibility
Accordion keyboard interactions follows the recommendations of the WAI-ARIA Authoring Practices for accordions.
Availability of accordion content to assistive technology requires the use of aria-controls and toggling aria-expanded as regions are expanded and collapsed.
# Keyboard Interactions
Key | description |
---|---|
Space
Enter
|
When focus is on a triggerAttrs element, toggles the section. |
Tab
|
Moves focus to the next focusable element. |
▼
|
Moves focus to the next triggerAttrs element. |
▲
|
Moves focus to the previous triggerAttrs element. |
Home
|
Moves focus to the first triggerAttrs element. |
End
|
Moves focus to the last triggerAttrs element. |
# API
# AccordionConfig
Property | Description | Default |
---|---|---|
multiple? |
boolean Allow multiple items to be opened at the same time. |
false |
value? |
Partial<T> | Partial<T>[] Initially expanded items. |
— |
disabled? |
boolean | Partial<T> | Partial<T>[] The disabled keys of the accordion. Pass to true to disable all the accordion items. |
false |
onValueChange? |
(value: undefined | Partial | Partial[]) => void Event handler called when the expanded state of the accordion changes. |
— |
# AccordionReturn
Property | Description |
---|---|
toggle |
(key: Partial) => void Toggles a key between expanded and collapsed. |
expand |
(keys: Partial[]) => void Expands a key or an array of keys. |
collapse |
(keys: Partial[]) => void Collapses a key or an array of keys. |
expandAll |
() => void Expands all the keys. |
collapseAll |
() => void Collapses all the keys. |
expanded |
Readable<Set<Partial<T>>> The expanded state of the accordion. |
disabled |
Writable<boolean | Partial<T> | Partial<T>[]> The disabled keys of the accordion. |
useAccordion |
Action<HTMLElement, void, Record<never, any>> Action for the accordion root element. |
itemAttrs |
Readable<Function> HTML attributes for the accordion item element. |
triggerAttrs |
Readable<Function> HTML attributes for the trigger element. |
contentAttrs |
Readable<Function> HTML attributes for the content element. |