ListItem

Import

import { List, ListItem } from '@delightstack/components';

Basic Usage

<List>
  <ListItem onclick={() => console.log('clicked')}>Click Me</ListItem>
</List>

Examples

List Appearance

Items sit on whatever surface the parent List provides. The list is transparent by default; the filled and outline props (on List, not ListItem) give it a surface or border — see the List page for details.

Plain (default)

• Profile
• Settings
• Sign out

Filled

• Profile
• Settings
• Sign out

Outline

• Profile
• Settings
• Sign out

View code

<!-- surface is controlled on the parent List -->
<List>…</List>
<List filled>…</List>
<List outline>…</List>

Navigation Links

ListItems can render as anchor elements when href is provided.

• Profile
• Settings
• Log Out

View code

<List>
  <ListItem href="/profile">Profile</ListItem>
  <ListItem href="/settings">Settings</ListItem>
  <ListItem onclick={handleLogout}>Log Out</ListItem>
</List>

Async Click Handling

When onclick returns a Promise, the row manages its own loading feedback — no loading prop required:

• Instant actions don’t flash. The spinner only appears if the promise is still pending after ~100ms; anything faster is treated as instant.
• The spinner can’t blink. Once shown, it stays for at least ~1s, then eases out quickly.
• Success is confirmed automatically. On resolve, a brief checkmark flashes; on reject, no checkmark is shown.

• Save Item (1.5s)
• Quick Action (instant)
• Sync Data (fails)

View code

<List>
  <ListItem onclick={async () => {
    await api.saveItem(); // throws on failure -> no checkmark
  }}>
    Save Item
  </ListItem>
</List>

Manual Success Checkmark

When you drive loading yourself (e.g. from a store), set loading_success to flash the same confirming checkmark as loading returns to false. Leave it off and the spinner simply disappears.

• With checkmark
• Without checkmark

View code

<List>
  <ListItem loading={loading} loading_success>Save Item</ListItem>
</List>

Content Slots

Use inline SVG or icons as leading/trailing content within list items.

• Profile
• Settings
• Notifications

View code

<List>
  <ListItem href="/profile">
    <UserIcon style="margin-right: 0.75rem;" />
    Profile
    <span style="flex: 1;" />
    <ChevronIcon />
  </ListItem>
  <ListItem href="/settings">
    <SettingsIcon style="margin-right: 0.75rem;" />
    Settings
    <span style="flex: 1;" />
    <ChevronIcon />
  </ListItem>
</List>

Submenu via Menu Snippet

Provide a menu snippet to show a more-options button with a dropdown.

• Document A
• Document B
• Document C

View code

<List>
  <ListItem>
    Document A
    {#snippet menu()}
      <List>
        <ListItem onclick={() => edit()}>Edit</ListItem>
        <ListItem onclick={() => duplicate()}>Duplicate</ListItem>
        <ListItem onclick={() => remove()}>Delete</ListItem>
      </List>
    {/snippet}
  </ListItem>
</List>

Active State

Force a selected/active appearance on an item.

• Currently Selected
• Another Item

View code

<List type="text">
  <ListItem active>Currently Selected</ListItem>
  <ListItem>Another Item</ListItem>
</List>

Disabled Item

• Unavailable Action
• Available Action

View code

<List type="text">
  <ListItem disabled>Unavailable Action</ListItem>
  <ListItem>Available Action</ListItem>
</List>

Props

Prop	Type	Default	Description
disabled	boolean	false	Disable interaction
active	boolean	false	Force active/selected appearance
loading	boolean	undefined	Show the loading spinner on the action row manually. Leave unset to let a promise-returning onclick drive it
loading_success	boolean	false	For the manual loading path: flash a success checkmark when loading goes true → false. The promise path shows it automatically on resolve
href	string	-	Render as an anchor link
target	'_self' | '_blank' | '_parent' | '_top'	-	Link target attribute
menu	Snippet	-	Submenu content (renders a more-options button)
popover_placement	Placement	'bottom-end'	Submenu popover position
popover_close_on_inside_click	boolean	false	Close submenu on inside click
id	string	auto	Element ID
class	string	''	Additional CSS classes
style	string	''	Additional inline styles
children	Snippet	-	Main content

Events

Event	Detail	Description
onclick	(e: MouseEvent) => void | Promise<void>	Click handler; return a Promise for automatic spinner + success-checkmark feedback
onchange	(value: boolean) => void	Called when selection state changes (radio/checkbox modes)

Accessibility

• Renders the appropriate interactive element based on the parent List type: <button>, <a>, <label>, or plain content
• aria-selected / aria-checked applied for selection states
• aria-disabled set on disabled anchor elements
• Keyboard navigation handled by the parent List
• Focus indicators via focus-visible
• Ripple feedback attachment for tactile click response