Accordion

Organizes content into collapsible sections, allowing users to focus on one or more sections at a time.

	<script lang="ts">
  import { Accordion } from "bits-ui";
  import CaretDown from "phosphor-svelte/lib/CaretDown";
 
  const items = [
    {
      value: "1",
      title: "What is the meaning of life?",
      content:
        "To become a better person, to help others, and to leave the world a better place than you found it."
    },
    {
      value: "2",
      title: "How do I become a better person?",
      content:
        "Read books, listen to podcasts, and surround yourself with people who inspire you."
    },
    {
      value: "3",
      title: "What is the best way to help others?",
      content: "Give them your time, attention, and love."
    }
  ];
</script>
 
<Accordion.Root class="w-full sm:max-w-[70%]" type="multiple">
  {#each items as item (item.value)}
    <Accordion.Item
      value={item.value}
      class="group border-b border-dark-10 px-1.5"
    >
      <Accordion.Header>
        <Accordion.Trigger
          class="flex w-full flex-1 select-none items-center justify-between py-5 text-[15px] font-medium transition-all [&[data-state=open]>span>svg]:rotate-180"
        >
          <span class="w-full text-left">
            {item.title}
          </span>
          <span
            class="inline-flex size-8 items-center justify-center rounded-[7px] bg-transparent transition-all hover:bg-dark-10"
          >
            <CaretDown class="size-[18px] transition-all duration-200" />
          </span>
        </Accordion.Trigger>
      </Accordion.Header>
      <Accordion.Content
        class="overflow-hidden text-sm tracking-[-0.01em] data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
      >
        <div class="pb-[25px]">
          {item.content}
        </div>
      </Accordion.Content>
    </Accordion.Item>
  {/each}
</Accordion.Root>

Overview

The Accordion component is a versatile UI element that organizes content into collapsible sections, enabling users to focus on specific information while reducing visual clutter. It's particularly useful for presenting large amounts of related content in a compact, navigable format.

Key Features

  • Customizable Behavior: Can be configured for single or multiple open sections.
  • Accessibility: ARIA attributes for screen reader compatibility and keyboard navigation.
  • Transition Support: CSS variables and data attributes for smooth transitions between states.
  • Flexible State Management: Supports controlled and uncontrolled state, take control if needed.
  • Compound Component Structure: Provides a set of sub-components that work together to create a fully-featured accordion.

Architecture

The Accordion component is composed of several sub-components, each with a specific role:

  • Root: The root element that wraps all accordion items and manages the overall state.
  • Item: Individual sections within the accordion.
  • Trigger: The button that toggles the visibility of the content.
  • Header: The title or heading of each item.
  • Content: The expandable/collapsible body of each item.

Structure

Here's an overview of how the Accordion component is structured in code:

	<script lang="ts">
	import { Accordion } from "bits-ui";
</script>
 
<Accordion.Root>
	<Accordion.Item>
		<Accordion.Header>
			<Accordion.Trigger />
		</Accordion.Header>
		<Accordion.Content />
	</Accordion.Item>
</Accordion.Root>

Reusable Components

If you're planning to use the Accordion component throughout your application, it's recommended to create reusable wrapper components to reduce the amount of code you need to write each time.

For each individual item, you need an Accordion.Item, Accordion.Header, Accordion.Trigger and Accordion.Content component. We can combine these into a single MyAccordionItem component that makes it easier to reuse.

MyAccordionItem.svelte
	<script lang="ts">
	import { Accordion, type WithoutChildrenOrChild } from "bits-ui";
 
	type Props = WithoutChildrenOrChild<Accordion.ItemProps> & {
		title: string;
		content: string;
	};
 
	let { title, content, ...restProps }: Props = $props();
</script>
 
<Accordion.Item {...restProps}>
	<Accordion.Header>
		<Accordion.Trigger>{item.title}</Accordion.Trigger>
	</Accordion.Header>
	<Accordion.Content>
		{content}
	</Accordion.Content>
</Accordion.Item>

We used the WithoutChildrenOrChild type helper to omit the child and children snippet props from Accordion.ItemProps, since we are opting out of using delegation and are already taking care of rendering the children as text via the content prop.

For our MyAccordion component, we'll accept all the props that Accordion.Root accepts, as well as an additional items prop that will be used to render the MyAccordionItem components.

MyAccordion.svelte
	<script lang="ts">
	import { Accordion, type WithoutChildrenOrChild } from "bits-ui";
	import MyAccordionItem from "$lib/components/MyAccordionItem.svelte";
 
	type Item = {
		value?: string;
		title: string;
		content: string;
		disabled?: boolean;
	};
 
	let {
		value = $bindable(),
		ref = $bindable(null),
		...restProps
	}: WithoutChildrenOrChild<Accordion.RootProps> & {
		items: Item[];
	} = $props();
</script>
 
<!--
 Since we have to destructure the `value` to make it `$bindable`, we need to use `as any` here to avoid
 type errors from the discriminated union of `"single" | "multiple"`.
 (an unfortunate consequence of having to destructure bindable values)
  -->
<Accordion.Root bind:value bind:ref {...restProps as any}>
	{#each items as item, i (item.title + i)}
		<MyAccordionItem {...item} />
	{/each}
</Accordion.Root>
+page.svelte
	<script lang="ts">
	import { MyAccordion, MyAccordionItem } from "$lib/components";
</script>
 
<MyAccordion type="single">
	<MyAccordionItem title="Item 1">Content 1</MyAccordionItem>
	<MyAccordionItem title="Item 2">Content 2</MyAccordionItem>
	<MyAccordionItem title="Item 3">Content 3</MyAccordionItem>
</MyAccordion>

Managing Value State

Bits UI offers several approaches to manage and synchronize the Accordion's value state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:value directive. This method automatically keeps your local state in sync with the accordion's internal state.

	<script lang="ts">
	import { Accordion } from "bits-ui";
	let myValue = $state<string[]>([]);
</script>
 
<button
	onclick={() => {
		myValue = ["item-1", "item-2"];
	}}
>
	Open Items 1 and 2
</button>
 
<Accordion.Root type="multiple" bind:value={myValue}>
	<Accordion.Item value="item-1">
		<!-- ... -->
	</Accordion.Item>
	<Accordion.Item value="item-2">
		<!-- ... -->
	</Accordion.Item>
	<Accordion.Item value="item-3">
		<!-- ... -->
	</Accordion.Item>
</Accordion.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates myValue when the accordion changes (e.g., via clicking on an item's trigger)
  • Allows external control (e.g., opening an item via a separate button)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onValueChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { Accordion } from "bits-ui";
	let myValue = $state<string[]>([]);
</script>
 
<Accordion.Root
	type="multiple"
	value={myValue}
	onValueChange={(value) => {
		myValue = value;
		// additional logic here.
	}}
>
	<Accordion.Item value="item-1">
		<!-- ... -->
	</Accordion.Item>
	<Accordion.Item value="item-2">
		<!-- ... -->
	</Accordion.Item>
	<Accordion.Item value="item-3">
		<!-- ... -->
	</Accordion.Item>
</Accordion.Root>

Use Cases

  • Implementing custom behaviors on value change
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the accordion's value state, use the controlledValue prop. This approach requires you to manually manage the value state, giving you full control over when and how the accordion responds to value change events.

To implement controlled state:

  1. Set the controlledValue prop to true on the Accordion.Root component.
  2. Provide a value prop to Accordion.Root, which should be a variable holding the current state.
  3. Implement an onValueChange handler to update the state when the internal state changes.
	<script lang="ts">
	import { Accordion } from "bits-ui";
	let myValue = $state("");
</script>
 
<Accordion.Root type="single" controlledValue value={myValue} onValueChange={(v) => (myValue = v)}>
	<!-- ... -->
</Accordion.Root>

When to Use

  • Implementing complex open/close logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

Single Type

Set the type prop to "single" to allow only one accordion item to be open at a time.

	<CustomAccordion type="single" />

Multiple Type

Set the type prop to "multiple" to allow multiple accordion items to be open at the same time.

	<CustomAccordion type="multiple" />

Default Open Items

To set default open items, pass them as the value prop, which will be an array if the type is "multiple", or a string if the type is "single".

	<CustomAccordion value={["A", "C"]} type="multiple" />
Content A
Content C

Disable Items

To disable an individual accordion item, set the disabled prop to true. This will prevent users from interacting with the item.

	<Accordion.Root type="single">
	<Accordion.Item value="item-1" disabled>
		<!-- ... -->
	</Accordion.Item>
</Accordion.Root>

Svelte Transitions

The Accordion component can be enhanced with Svelte's built-in transition effects or other animation libraries.

Using forceMount and child Snippets

To apply Svelte transitions to Accordion components, use the forceMount prop in combination with the child snippet. This approach gives you full control over the mounting behavior and animation of the Accordion.Content.

	<Accordion.Content forceMount={true}>
	{#snippet child({ props, open })}
		{#if open}
			<div {...props} transition:slide={{ duration: 1000 }}>
				This is the accordion content that will transition in and out.
			</div>
		{/if}
	{/snippet}
</Accordion.Content>

In this example:

  • The forceMount prop ensures the components are always in the DOM.
  • The child snippet provides access to the open state and component props.
  • Svelte's #if block controls when the content is visible.
  • Transition directives (transition:fade and transition:fly) apply the animations.
	<script lang="ts">
  import { Accordion } from "bits-ui";
  import CaretDown from "phosphor-svelte/lib/CaretDown";
  import { slide } from "svelte/transition";
 
  const items = [
    {
      title: "What is the meaning of life?",
      content:
        "To become a better person, to help others, and to leave the world a better place than you found it."
    },
    {
      title: "How do I become a better person?",
      content:
        "Read books, listen to podcasts, and surround yourself with people who inspire you."
    },
    {
      title: "What is the best way to help others?",
      content: "Give them your time, attention, and love."
    }
  ];
 
  let value = $state<string[]>([]);
</script>
 
<Accordion.Root class="w-full sm:max-w-[70%]" type="multiple" bind:value>
  {#each items as item, i}
    <Accordion.Item value={`${i}`} class="group border-b border-dark-10 px-1.5">
      <Accordion.Header>
        <Accordion.Trigger
          class="flex w-full flex-1 items-center justify-between py-5 text-[15px] font-medium transition-all [&[data-state=open]>span>svg]:rotate-180"
        >
          {item.title}
          <span
            class="inline-flex size-8 items-center justify-center rounded-[7px] bg-transparent transition-all hover:bg-dark-10"
          >
            <CaretDown class="size-[18px] transition-all duration-200" />
          </span>
        </Accordion.Trigger>
      </Accordion.Header>
      <Accordion.Content
        forceMount={true}
        class="overflow-hidden text-sm tracking-[-0.01em]"
      >
        {#snippet child({ props, open })}
          {#if open}
            <div {...props} transition:slide={{ duration: 1000 }}>
              <div class="pb-[25px]">
                {item.content}
              </div>
            </div>
          {/if}
        {/snippet}
      </Accordion.Content>
    </Accordion.Item>
  {/each}
</Accordion.Root>

Best Practices

For cleaner code and better maintainability, consider creating custom reusable components that encapsulate this transition logic.

MyAccordionContent.svelte
	<script lang="ts">
	import { Accordion, type WithoutChildrenOrChild } from "bits-ui";
	import type { Snippet } from "svelte";
	import { fade } from "svelte/transition";
 
	let {
		ref = $bindable(null),
		duration = 200,
		children,
		...restProps
	}: WithoutChildrenOrChild<Accordion.ContentProps> & {
		duration?: number;
		children: Snippet;
	} = $props();
</script>
 
<Accordion.Content forceMount bind:ref {...restProps}>
	{#snippet child({ props, open })}
		{#if open}
			<div {...props} transition:fade={{ duration }}>
				{@render children?.()}
			</div>
		{/if}
	{/snippet}
</Accordion.Content>

You can then use the MyAccordionContent component alongside the other Accordion primitives throughout your application:

	<Accordion.Root>
	<Accordion.Item value="A">
		<Accordion.Header>
			<Accordion.Trigger>A</Accordion.Trigger>
		</Accordion.Header>
		<MyAccordionContent duration={300}>
			<!-- ... -->
		</MyAccordionContent>
	</Accordion.Item>
</Accordion.Root>

API Reference

Accordion.Root

The root accordion component used to set and manage the state of the accordion.

Property Type Description
type required
enum

The type of accordion. If set to 'multiple', the accordion will allow multiple items to be open at the same time. If set to single, the accordion will only allow a single item to be open.

Default: undefined
value $bindable
union

The value of the currently active accordion item. If type is 'single', this should be a string. If type is 'multiple', this should be an array of strings.

Default: undefined
onValueChange
function

A callback function called when the active accordion item value changes. If the type is 'single', the argument will be a string. If type is 'multiple', the argument will be an array of strings.

Default: undefined
controlledValue
boolean

Whether or not the value is controlled or not. If true, the component will not update the value state internally, instead it will call onValueChange when it would have otherwise, and it is up to you to update the value prop that is passed to the component.

Default: false
disabled
boolean

Whether or not the accordion is disabled. When disabled, the accordion cannot be interacted with.

Default: false
loop
boolean

Whether or not the accordion should loop through items when reaching the end.

Default: false
orientation
enum

The orientation of the accordion.

Default: vertical
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-orientation
enum

The orientation of the component.

data-disabled
''

Present when the component is disabled.

data-accordion-root
''

Present on the root element.

Accordion.Item

An accordion item.

Property Type Description
disabled
boolean

Whether or not the accordion item is disabled.

Default: false
value
string

The value of the accordion item. This is used to identify when the item is open or closed. If not provided, a unique ID will be generated for this value.

Default: A random unique ID
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

Whether the accordion item is open or closed.

data-disabled
''

Present when the component is disabled.

data-orientation
enum

The orientation of the component.

data-accordion-item
''

Present on the item element.

Accordion.Header

The header of the accordion item.

Property Type Description
level
union

The heading level of the header. This will be set as the aria-level attribute.

Default: 3
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-orientation
enum

The orientation of the component.

data-disabled
''

Present when the component is disabled.

data-heading-level
enum

The heading level of the element.

data-accordion-header
''

Present on the header element.

Accordion.Trigger

The button responsible for toggling the accordion item.

Property Type Description
ref $bindable
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-orientation
enum

The orientation of the component.

data-disabled
''

Present when the component is disabled.

data-accordion-trigger
''

Present on the trigger element.

Accordion.Content

The accordion item content, which is displayed when the item is open.

Property Type Description
forceMount
boolean

Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.

Default: false
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-orientation
enum

The orientation of the component.

data-disabled
''

Present when the component is disabled.

data-accordion-content
''

Present on the content element.

CSS Variable Description
--bits-accordion-content-height

The height of the accordion content element.

--bits-accordion-content-width

The width of the accordion content element.