SidebarSection handbook

v1.5.0 · @snowui-design-system/components

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

Organize Sidebar navigation into titled groups with expand/collapse controls and optional actions, making long navigation lists easier to browse.

When to use it

Use it for a titled navigation group inside Sidebar. Do not add another Separator when the group already supplies one; use SidebarItem for its children.

id identifies the group, title names it, and children contains navigation items.
collapsible and collapsed control group collapse; defaultCollapsed sets the initial state. actions supplies group-level controls.
Built-in expand/collapse accessible names follow LocaleProvider. The caller owns title and action.label; their text is preserved.

Quick start

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

<script lang="ts">	import { SidebarItem, SidebarSection } from '@snowui-design-system/components';	let opened = $state('');</script> <div style="width: min(100%, 12rem);"><SidebarSection id="documentation" title="Documentation">    <SidebarItem id="introduction" label="Introduction" onSelect={() => opened = 'Introduction'} />    <SidebarItem id="quick-start" label="Quick Start" updated onSelect={() => opened = 'Quick Start'} />    <SidebarItem id="components" label="Components" onSelect={() => opened = 'Components'} /></SidebarSection></div>

API

Keyword	Type	Default	Description
id	`string`	`required`	Stable group identifier
title	`string`	—	Built-in group title; the title row is omitted when absent
collapsible	`boolean`	—	Whether to show the built-in expand/collapse button. Defaults to `true` when a title is present.
collapsed	`boolean`	—	Controls the group’s collapsed state when a boolean is supplied. If omitted, the group’s internal state and Sidebar’s persisted state manage it.
defaultCollapsed	`boolean`	`false`	Initial uncontrolled state
onCollapsedChange	`(collapsed: boolean) => void`	—	Callback when the group’s collapsed state changes
actions	`SidebarActionData[] \| Snippet`	`[]`	Zero or more title actions; an array creates `Button bare` controls
children	`Snippet`	—	Group content
parts	`ComponentPartsOf<{ Button: typeof Button; Separator: typeof Separator; }>`	—	Configures Buttons created from data and the built-in Separator

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

API reference

Long titles use Text single-line truncation and retain the complete accessible name without adding a title Tooltip. The arrow and trailing actions keep their dimensions; effective spacing between the title and actions stays at least 4 CSS px. The header height accommodates the built-in 12px icon minimum plus vertical padding to prevent clipping at small root font sizes. Body layout, separators and whole-sidebar collapse timing are preserved.

When the whole Sidebar collapses, the title row first fades through the Frame color bridge. Only after opacity reaches zero do its height, vertical padding, and Section gap collapse through the Frame size bridge, so content Items move upward after the title disappears. The title node remains in the DOM; inert, aria-hidden, and delayed visibility: hidden prevent interaction during collapse. When a section itself collapses, its content subtree is not rendered. If collapsed was omitted, do not write a click’s internal state back as a controlled Prop: that would override Sidebar’s persisted state and prevent reopening. Sidebar remembers which Section owns the active item before collapsing, so restoring after refresh does not require hidden content to remain in the DOM. Each section includes a horizontal Separator after its content; SidebarSection retains it while expanded, while the section collapses, and while the entire Sidebar collapses. Callers need not add one. This separator and any horizontal Separator explicitly composed in Sidebar share Sidebar’s four-sided 8px padding, zero line height, and horizontal/vertical padding overrides. Its own appearance can still be set through parts.Separator. The title row has default horizontal padding of 8px (var(--padding-2)) and vertical padding of 4px (var(--padding-1)) across the title, arrow, and actions. A titled section is collapsible by default. Its title and arrow share one Button bare emphasis="muted"; the full title area is clickable, with no Tooltip. A data-defined action can select the matching SnowUI icon with iconCollection: "snowui"; its Tooltip appears to the right of the button. Title action buttons use var(--gap-2) (8px) spacing and muted emphasis for a 40% opacity secondary appearance that rises to 100% on hover.

SidebarSection style overrides

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

Variable	Purpose and default reference
`--snowui-sidebar-section-gap-override`	Spacing inside a section (default `var(--gap-1)`)
`--snowui-sidebar-section-title-font-size-override`	Section title font size (default `var(--text-12)`)
`--snowui-sidebar-section-title-line-height-override`	Section title line height (default `var(--leading-12)`)
`--snowui-sidebar-section-title-padding-x-override`	Title row horizontal padding (default `var(--padding-2)` = 8px)
`--snowui-sidebar-section-title-padding-y-override`	Title row vertical padding (default `var(--padding-1)` = 4px)

Design guide · Tokens · Composition boundaries

SidebarSection types and states

Required Prop: id.

Two-way binding: bind:collapsed.

Inherited declaration: Omit<FrameProps, "children" | "id">. Consult the base component’s public documentation for inherited capabilities; fields excluded by Omit cannot be used as if inherited unchanged.

Shared Frame API · Back to API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

SidebarActionData

Source: components/src/blocks/sidebar-context.svelte.ts

export interface SidebarActionData {    id: string;    icon: string;    iconCollection?: string;    label: string;    disabled?: boolean;    onSelect?: (ownerId: string) => void;}

ComponentPartsOf

Source: components/src/logic/component-parts.svelte.ts

export type ComponentPartsOf<    T extends Record<string, Component<any>>,> = {    [K in keyof T]?: ConfigurableComponentPartProps<T[K]>;};

ConfigurableComponentPartProps

Source: components/src/logic/component-parts.svelte.ts

export type ConfigurableComponentPartProps<C extends Component<any>> = Partial<    Omit<ComponentProps<C>, ComponentPartControlledKey>>;

ComponentPartControlledKey

Source: components/src/logic/component-parts.svelte.ts

export type ComponentPartControlledKey =    | "children"    | "as"    | "value"    | "defaultValue"    | "open"    | "selected"    | "checked"    | "disabled"    | "readonly"    | "id"    | `on${string}`    | `aria-${string}`;