Accordion handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Expand or collapse content sections to scan dense information while keeping the page compact.

When to use it

Suitable for FAQ, setting grouping and foldable instructions. Use Tab when you need to switch the content panel of the same area; AccordionItem should be placed in Accordion.

• type="single" uses string values, multiple uses arrays; bind:value expands items synchronously, and defaultValue only provides the initial state.

• items mode uses stringified indices as values. Generated titles truncate on one line while retaining their complete accessible name; parts.Text configures that title text. Explicit children replace items and configure themselves rather than reading generated-child parts.

• The Icon as="leading" in Accordion inherits the Accordion icon size when size is not explicitly specified: sm/md/lg are 16/20/24 respectively; Icon that does not declare leading does not participate in this inheritance, and the explicit size takes precedence.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Accordion, AccordionItem, Frame, Icon, Text } from '@snowui-design-system/components';	import { BookOpen, Package, Palette, Rocket, ShieldCheck } from '@snowui-design-system/resource-svelte';</script> <Accordion type="multiple" defaultValue={['installation', 'themes']} variant="filled" size="md" style="width: min(100%, 36rem);">	<AccordionItem value="installation">		<Frame as="title" singleLine><Icon as="leading"><Package /></Icon><Text lines={1}>How do I install SnowUI?</Text></Frame>		<Frame as="content" row>Install @snowui-design-system/components and import its styles. The Resource package is optional for examples that use its icons.</Frame>	</AccordionItem>	<AccordionItem value="components">		<Frame as="title" singleLine><Icon as="leading"><BookOpen /></Icon><Text lines={1}>Where can I explore every component?</Text></Frame>		<Frame as="content" row>Open the Components catalog for live previews, copy-ready code, API details, and source links.</Frame>	</AccordionItem>	<AccordionItem value="themes">		<Frame as="title" singleLine><Icon as="leading"><Palette /></Icon><Text lines={1}>Does SnowUI support light and dark themes?</Text></Frame>		<Frame as="content" row>Yes. Components use the same semantic theme contract in applications and isolated documentation previews.</Frame>	</AccordionItem>	<AccordionItem value="quality">		<Frame as="title" singleLine><Icon as="leading"><ShieldCheck /></Icon><Text lines={1}>How are components verified?</Text></Frame>		<Frame as="content" row>Public behavior is checked with type validation, accessibility coverage, and real browser previews.</Frame>	</AccordionItem>	<AccordionItem value="pro">		<Frame as="title" singleLine><Icon as="leading"><Rocket /></Icon><Text lines={1}>When do I need a paid license?</Text></Frame>		<Frame as="content" row>Source is available under the Free license. Publishing a real product or delivering it to a client requires Pro or Team; project and developer limits also apply.</Frame>	</AccordionItem></Accordion>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Feature overview

• The built-in mode renders items containing title and content strings. It generates AccordionItem, Frame as="title|content" and title Text. Titles use singleLine and Text lines={1} by default; bodies are not forced onto one line. Configure them through parts.Frame / parts.Text, and prefer explicit composition for complex content.

• Replace the built-in items when explicit children exist, which is used to customize the AccordionItem structure.

• Support single opening and multi-opening modes.

• Support uncontrolled defaultValue and controlled value.

• Support variant="filled" | "divided" two visual forms.

• Support size="sm" | "md" | "lg" three-speed density.

• Expand the text by default to the theme adaptive Black/40% secondary text color; the title continues to inherit the host's foreground.

• Hover does not display the background, only changes the color of the default indicator icon in the title.

• Only the title can be clicked to expand or close; the body text, blank space and interactive descendants do not trigger switching.

• By default, indicatorVariant="cross" reuses the same ComponentIcon plus, and only rotates 45° to get ×; indicatorVariant="minus" retains the old plus/minus switch and half-circle rotation. External trailing continues to replace the default icon.

Core attributes

The value of the default built-in mode is an array index string, for example, defaultValue="1" expands the second item by default. The explicit combination mode still uses the stable value declared by AccordionItem itself. The size is only controlled by Accordion size, and AccordionItem does not provide independent size attributes.

Layout model

Main layout model: composite management layout. See the definition.. /.. /../specs/maintainers/LayoutProtocol.md §12.6 (source code reference: specs/maintainers/LayoutProtocol.md).

Structure:

• Root Frame (composite container, providing AccordionContext)

  • AccordionItem (single container, responsible for background, rounded corners, separating lines and unfolding status)

    • Frame as="title" (title trigger)

    • Frame as="content" (expand content region)

Source of local layout:

Padding belongs to: Frame as="title" is responsible for the clickable area padding; Frame as="content" is responsible for the body padding, Root does not repeat the production of outer padding. Gap attribution: Root manages sub-item spacing through --snowui-accordion-gap; Title and Content internal slot spacing is managed by --snowui-accordion-trigger-gap. Scrolling attribution: Accordion itself does not create a scrolling area.

Hover attribution: title hover only changes the transparency of the default indication icon, does not create a shared background layer, and does not enable title hover overlay.

Design draft mapping:

Style variable chain

See the Accordion section of components.css (source code reference: components/src/styles/components.css) for the public coverage entrance.

Barrier-free

• The root node outputs role, and the default is presentation; the consumer can be overwritten by role.

• Frame as="title" is taken over by AccordionItem by button-like semantics, and outputs role="button", tabindex, aria-expanded, aria-controls.

• Title output aria-expanded, aria-controls.

• Content output role="region" and aria-labelledby.

• Disable Title output aria-disabled="true" and remove it from the tab order.

• The semantics of pointer and keyboard switching only belong to Title; the click of body text, blank space and interactive controls does not change the expansion state.

Usage examples

<Accordion    defaultValue="0"    items={[        { title: "Basic settings", content: "Basic content." },        { title: "Advanced settings", content: "Advanced content." },    ]}/> <Accordion defaultValue="basic">    <AccordionItem value="basic">        <Frame as="title" singleLine>            <Text lines={1}>Basic settings</Text>        </Frame>        <Frame as="content" row>Basic content.</Frame>    </AccordionItem>     <AccordionItem value="advanced">        <Frame as="title" singleLine>            <Text lines={1}>Advanced settings</Text>            <Icon as="trailing"><Resource.Plus /></Icon>        </Frame>        <Frame as="content" row>An external trailing icon replaces the default arrow.</Frame>    </AccordionItem></Accordion>

This section is protected. An AI must request user review before modifying it.