List · SWSHD Documentation

Overview

List groups related rows for preferences, account details, navigation, and other short lists. Compose ListRoot, ListSection, and ListItemfrom independent imports. A section can also stand alone.

List belongs in Components: its sections and rows are reusable presentation and interaction building blocks. A settings screen that selects rows, loads preferences, and saves changes is a product composition. The names follow the familiar list, section, and item vocabulary used by platform design systems.

The grouped layout is based on the settings reference. All styling uses existing SWSHD semantics.

Sections with controls

The trailing child is a slot for an existing component such as Switch. Toggle either preference to try the controlled state. Use a static item's footer slot for expanded fields or related actions below the row.

Privacy & access

Require password

Lock the album with a password

Content & uploads

Comments

Let guests message about the album

Actions, links, and values

An onPress row is a button; an href row is a real link. Both show a disclosure chevron. Use showDisclosure={false} for an inline action, such as adding an item. An item without an action, link, or disabled state is static and can display trailing information. A disabled-only item remains an unavailable action. Try Edit profile with a click, Enter, or Space.

Account

Language

English

Help center

Profile opened: 0

Usage

import ListRoot from "swshd/List/Root";
import ListSection from "swshd/List/Section";
import ListItem from "swshd/List/Item";
import Switch from "swshd/Switch";
import IconMessages from "swshd/icons/IconMessages";

<ListRoot>
  <ListSection title="Content & uploads">
    <ListItem
      title="Comments"
      description="Let guests message about the album"
      Icon={IconMessages}
    >
      <Switch
        value={comments}
        onValueChange={setComments}
        accessibilityLabel="Comments. Let guests message about the album"
      />
    </ListItem>
    <ListItem title="Manage uploads" onPress={openUploads} />
  </ListSection>
</ListRoot>

Tokens and layout

Sections use spacing.xl separation, spacing.sm heading gap, and radius.md. Rows use spacing.sm horizontal inset and icon gap, spacing.sm vertical inset, and a 24-point icon. The copy column shrinks and wraps; the trailing slot keeps its intrinsic width. Section headings share the row inset, aligning with leading icons.

Sections add SWSHD dividers between visible rows, including rows inside fragments. Dividers share the row's horizontal inset. Use dividers={false} when composing related controls or a field group that already owns its separators.

Headings use label-md, titles body-lg, and descriptions body-md. Groups use fill.raised.default so they remain distinct from the modal and sheet background, bg.elevated. The theme supplies text.primary for titles, text.muted for descriptions, headings, and icons, and fill.subtle for action feedback. Destructive titles and icons use status.danger.

Accessibility and state

Section headings label their lists through unique IDs; items use list-item semantics. Set headingLevel to fit the page hierarchy. Untitled sections and an explicit accessibilityLabel are supported. Section containers add no keyboard stops. Icons and chevrons are decorative.

Action rows inherit Touchable's focus, keyboard, disabled, and link behavior. Each description is associated with its action on web and included in its accessible name on native. External links opened in a new tab default to rel="noopener noreferrer".

A static control row can set headingLevel on ListItem when its title introduces a group of controls. This preserves heading navigation while keeping the standard row typography.

Expanded content aligns with the title by default. Use footerAlignment="row"for controls and editors that need the row's full padded width beneath its icon.

Link destinations must be non-empty; blank and whitespace-only values are rejected.

A trailing control owns its accessible name, value, handler, and disabled/loading state. Include important explanatory copy in its accessible name. Control rows are ordinary layouts: their copy is not an additional click target. TypeScript prevents combining a trailing child with an action, which would nest interactive controls.

An action's loading prop shows progress and exposes busy state. Set disabled separately when pending work must block presses; a language picker can stay available while a translation loads.

API

Prop	Type	Default	Description
`ListRoot.children`	`composed elements`	—	A stack of sections; conditional and mapped elements are supported.
`ListSection.dividers`	`boolean`	`true`	Inset SWSHD dividers between rows. Disable for related controls or custom field separators.
`ListSection.title`	`string`	—	Optional mono heading outside the surface.
`ListSection.headingLevel`	`1 \| 2 \| 3 \| 4 \| 5 \| 6`	`3`	Accessible heading level; typography stays label-md.
`ListSection.accessibilityLabel`	`string`	—	Override the list name or label an untitled section.
`ListSection.children`	`composed elements`	—	Rows inside one grouped surface.
`ListItem.title`	`string`	—	Required primary text.
`ListItem.headingLevel`	`1 \| 2 \| 3 \| 4 \| 5 \| 6`	—	Optional accessible heading level for a static control row; typography stays body-lg.
`ListItem.description`	`string`	—	Optional wrapping supporting text.
`ListItem.Icon`	`IconComponent`	—	Optional decorative leading SWSHD icon.
`ListItem.children`	`ReactElement \| null`	—	Trailing content/control; only available on static rows.
`ListItem.footer`	`ReactElement \| null`	—	Expanded fields or related actions aligned with a static row's text column; not available on action rows.
`ListItem.footerAlignment`	`"content" \| "row"`	`content`	Align the footer with the title or the full padded row width. Static rows only.
`ListItem.showDisclosure`	`boolean`	`true`	Show the action row's navigation chevron. Hide for inline actions; loading still shows progress.
`ListItem.loading`	`boolean`	`false`	Action progress indicator and busy state. Use disabled separately to block interaction.
`ListItem.onPress / href`	`() => void / string`	—	Make the row an action or link. Mutually exclusive with children and footer.
`ListItem.disabled`	`boolean`	`false`	Disables an action/link. A trailing control owns its own disabled state.
`ListItem.destructive`	`boolean`	`false`	Semantic danger ink for the title and icon.
`ListItem.accessibilityLabel / accessibilityState`	`Touchable props`	—	Override an action's name or expose its busy/expanded state.
`ListItem.target / rel / download / linkUrlScheme`	`Touchable props`	—	Forwarded to link hosts.
`testID`	`string`	—	Supported by all three parts.