Accordion

Allow the user to toggle the display of a section of content.

# 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.