ListItem

Overview

ListItem supplies the visual layout shared by list and menu rows. It renders a div by default for passive content. Use ListItemButton for ordinary action rows. Compose ListItem with an anchor for navigation or with a custom semantic owner when needed. Use Dropdown or Select when you need a complete popup or selection owner.

Usage

import { IconBell } from 'twenty-ui/icon';
import { ListItem } from 'twenty-ui/primitives/navigation';

export const NotificationRow = () => (
  <ListItem startIcon={<IconBell />}>Notifications</ListItem>
);

Anatomy

ListItem exposes content slots through props. These slots arrange content inside one row; they are not separately exported components.

ListItem
├── startIcon
├── children
├── description
├── actions
└── endIcon

Slot	Requirement	Purpose
`children`	Required for a visible row label	Supplies the main text.
`startIcon`, `endIcon`	Optional	Add icons, avatars, metadata, or independent controls at either end.
`description`	Optional	Adds supporting content inline, below the label, or at the end.
`actions`	Optional	Adds trailing content, such as a separately focusable action.
`indicator`, `shortcut`, `hasSubmenu`	Optional	Configure built-in selection marks, shortcut hints, and the submenu indicator.

The row supplies layout. render accepts an element or a callback that receives native props and visual state. Spread those props onto the actual root when using a callback. Native attributes, event handlers, className, style, and ref reach that root. For a row with independent action buttons, keep the row itself non-interactive so those buttons remain separate controls.

Multiline rows

Set descriptionPlacement="below" to place supporting content beneath the label. The title keeps its existing truncation behavior, and supporting content wraps with the available width. The default inline placement and the end placement retain their existing appearance.

import { Avatar } from 'twenty-ui/primitives/data-display';
import { ListItem } from 'twenty-ui/primitives/navigation';
import { Text } from 'twenty-ui/primitives/typography';

export const PlanningRow = () => (
  <ListItem
    descriptionPlacement="below"
    startIcon={<Avatar name="Alex Morgan" size="md" imageProps={{ alt: '' }} />}
    description="Review the proposed timeline and confirm the next steps with the team."
    endIcon={
      <Text render={<span />} size="sm" color="secondary">
        09:48
      </Text>
    }
  >
    Quarterly planning
  </ListItem>
);

For shorter previews, pass a Text component with truncate or lineClamp as description. Custom content controls its own layout and accessible labels.

Independent visual states

All visual state belongs to the caller. active identifies the open or current row without selecting it. selected represents selection, and focused represents a keyboard navigation highlight without moving DOM focus. active applies the current-row background. Set selectionAppearance="accent" for an accent fill on selected rows, independently of description placement. The default appearance preserves the existing indicator-based selection styling. focused applies the shared highlighted background, including when an owner uses it for pointer highlighting. The focus-visible outline follows actual keyboard focus on the root or its controls. These props do not add accessible states. Supply aria-current, aria-selected, or a control’s checked state on the appropriate semantic owner. Actual keyboard focus also retains the native focus-visible outline.

Independent controls

Keep the default div root when a row contains a real checkbox or independent action buttons. Use startIcon for the checkbox and actions for buttons. The decorative indicator is unnecessary when a real checkbox already displays selection.

import { useState } from 'react';
import { Button, Checkbox } from 'twenty-ui/primitives/input';
import { ListItem } from 'twenty-ui/primitives/navigation';

type SelectablePlanningRowProps = {
  active?: boolean;
  disabled?: boolean;
  onOpen: () => void;
};

export const SelectablePlanningRow = ({
  active = false,
  disabled = false,
  onOpen,
}: SelectablePlanningRowProps) => {
  const [selected, setSelected] = useState(false);

  return (
    <ListItem
      active={active}
      selected={selected}
      selectionAppearance="accent"
      disabled={disabled}
      descriptionPlacement="below"
      description="Review the proposed timeline and confirm the next steps with the team."
      startIcon={
        <Checkbox
          aria-label="Select quarterly planning"
          checked={selected}
          onCheckedChange={setSelected}
          disabled={disabled}
        />
      }
      actions={
        <Button variant="ghost" size="sm" onClick={onOpen} disabled={disabled}>
          Open
        </Button>
      }
    >
      Quarterly planning
    </ListItem>
  );
};

Selection and opening are separate interactions. The application owns event propagation and any row activation or keyboard policy. ListItem.disabled changes appearance only; pass disabled to each real control to prevent its activation. The existing action visibility behavior applies to multiline rows: actionsVisibility="hover" reveals actions on hover or focus within the row and keeps them visible on touch devices. Set it to always for persistent actions, including while a caller-owned popup is open. At row widths of 480px or less, multiline actions move to their own line and wrap as needed.

Action row

Use ListItemButton to pair row styling with native button interaction. Pass disabled once to control both appearance and activation.

import { ListItemButton } from 'twenty-ui/components/navigation';
import { IconCopy } from 'twenty-ui/icon';

type DuplicateActionProps = {
  onDuplicate: () => void;
  disabled?: boolean;
};

export const DuplicateAction = ({
  onDuplicate,
  disabled = false,
}: DuplicateActionProps) => (
  <ListItemButton
    disabled={disabled}
    startIcon={<IconCopy />}
    description="Create a copy"
    onClick={onDuplicate}
  >
    Duplicate
  </ListItemButton>
);

A custom button owner can still compose ListItem through render. That owner supplies native focus, Enter and Space activation, and disabled behavior. ListItem.disabled supplies only the matching visual style. shortcut displays hints; your application registers the shortcuts. Pass an anchor through render when the entire row navigates. Put anchor attributes, including href, target, and rel, on that element.

import { ListItem } from 'twenty-ui/primitives/navigation';

export const DocumentationLink = () => (
  <ListItem render={<a href="https://twenty.com/developers" />}>
    Typography documentation
  </ListItem>
);

String labels stay text, including URL-shaped strings. ListItem does not create links. To link part of a non-interactive row, supply an anchor as caller-owned content. Keep that row as a div to avoid nested links or buttons. String labels retain their truncation and overflow tooltip; custom content can use OverflowingTextWithTooltip with an explicit rendered anchor. Links do not have a native disabled attribute. If a destination is unavailable, the link owner must supply the appropriate semantics, tab order, and navigation policy. Styling it with ListItem.disabled alone does not prevent navigation. Use Dropdown.ActionItem or Dropdown.OptionItem inside their popup owner. These parts already compose the ListItem layout and expose its visual slots. The popup owner supplies roles, focus, keyboard navigation, activation, and disabled behavior.

import { Button } from 'twenty-ui/primitives/input';
import { Dropdown } from 'twenty-ui/components/navigation';

type RecordActionsProps = { onDuplicate: () => void };

export const RecordActions = ({ onDuplicate }: RecordActionsProps) => (
  <Dropdown.Root type="menu">
    <Dropdown.Trigger render={<Button>Record actions</Button>} />
    <Dropdown.Content>
      <Dropdown.ActionItem onClick={onDuplicate}>
        Duplicate record
      </Dropdown.ActionItem>
      <Dropdown.ActionItem disabled>Unavailable action</Dropdown.ActionItem>
    </Dropdown.Content>
  </Dropdown.Root>
);

Native event policy

ListItem forwards native event objects and handlers. Clicks bubble normally, including clicks on trailing action controls. Put any intentional boundary on the interactive owner or caller’s handler.

import { ListItem } from 'twenty-ui/primitives/navigation';

type OpenRecordProps = { onOpen: () => void };

export const OpenRecord = ({ onOpen }: OpenRecordProps) => (
  <ListItem
    render={<button type="button" />}
    onClick={(event) => {
      event.stopPropagation();
      onOpen();
    }}
  >
    Open record
  </ListItem>
);

The caller also owns any preventDefault() policy, such as preventing a link’s navigation. Passing onClick does not add a role, make a div keyboard-operable, or change propagation. Compose reorderable rows with ListItem inside your application’s drag host. Put the host’s drag attributes and listeners on its handle, and pass the handle or grip through startIcon. Keep independent visibility, edit and delete controls in actions. The drag host owns pointer and keyboard reordering, disabled dragging and accessible handle labels. For editor suggestions, keep the editor’s existing listbox and active option owner. Render each ListItem with role="option" and aria-selected, and use focused for the active row’s appearance. The editor owns arrow navigation and Enter activation while focus stays in the editing surface. Prevent pointer-down focus changes when the editor requires them, and handle pointer selection in the application’s row handler. For suggestions in a Dropdown page, use Dropdown.OptionItem or Dropdown.ActionItem so that page owns navigation and activation. Do not add a second Enter or Space handler to an owner that already activates from the keyboard.

Settings row

Use SettingsRow for a labeled switch row. It composes ListItem and Switch, manages their accessible association, and uses the switch’s disabled state for the row’s appearance.

Selection indicator

import { useState } from 'react';
import { ListItem } from 'twenty-ui/primitives/navigation';

export const ShowArchivedToggle = () => {
  const [selected, setSelected] = useState(false);

  return (
    <ListItem
      render={<button type="button" aria-pressed={selected} />}
      selected={selected}
      indicator="check"
      onClick={() => setSelected(!selected)}
    >
      Show archived records
    </ListItem>
  );
};

active, selected, focused, and disabled independently control row styling. They do not register actions, move DOM focus, add accessible roles or states, or suppress events. The check and checkbox indicators are decorative; use a real Checkbox for a form control. Set aria-pressed, aria-selected, or other state semantics on the owner that needs them.

Picker rows

Selection belongs to the parent. ListItem has no uncontrolled selection state: pass selected and update it from onClick. Use indicator="check" for a single choice and indicator="checkbox" for multiple choices. Both indicators are decorative; the interactive owner handles activation. In an existing listbox, pass role="option" and aria-selected, and keep focus and arrow-key handling in the listbox. For a complete selection widget, use Select. Standalone selection buttons can use aria-pressed, as in these examples.

Single selection

Place an Avatar in startIcon to identify a record. Use description for supporting text, and descriptionPlacement="end" for a trailing value.

import { useState } from 'react';
import { Avatar } from 'twenty-ui/primitives/data-display';
import { ListItem } from 'twenty-ui/primitives/navigation';

export const AssigneeButtons = () => {
  const [assignee, setAssignee] = useState<string | null>(null);

  return (
    <div role="group" aria-label="Assignee">
      {['Alex Morgan', 'Sam Taylor'].map((name) => (
        <ListItem
          key={name}
          render={<button type="button" />}
          aria-pressed={assignee === name}
          selected={assignee === name}
          indicator="check"
          startIcon={<Avatar name={name} size="md" imageProps={{ alt: '' }} />}
          onClick={() => setAssignee(name)}
        >
          {name}
        </ListItem>
      ))}
    </div>
  );
};

Multiple selection

Compose Tag as the row content for tagged values, or put ColorSample in startIcon for a color choice. A row can also contain plain text or an avatar.

import { useState } from 'react';
import { Tag } from 'twenty-ui/primitives/data-display';
import { ListItem } from 'twenty-ui/primitives/navigation';

export const TeammateButtons = () => {
  const [teammates, setTeammates] = useState<string[]>([]);

  const toggleTeammate = (name: string) => {
    setTeammates((current) =>
      current.includes(name)
        ? current.filter((teammate) => teammate !== name)
        : [...current, name],
    );
  };

  return (
    <div role="group" aria-label="Teammates">
      {['Alex Morgan', 'Sam Taylor'].map((name) => (
        <ListItem
          key={name}
          render={<button type="button" />}
          aria-pressed={teammates.includes(name)}
          selected={teammates.includes(name)}
          indicator="checkbox"
          onClick={() => toggleTeammate(name)}
        >
          <Tag color="blue">{name}</Tag>
        </ListItem>
      ))}
    </div>
  );
};

The checkbox indicator is not a form control and does not submit a value. Use Checkbox when you need form participation. Set native disabled on the rendered button to prevent activation and remove it from the tab order. Also pass ListItem.disabled for its visual appearance.

Slots

Use startIcon and endIcon for icons or caller-owned content, description for supporting text, actions for trailing content, and hasSubmenu for a submenu indicator. descriptionPlacement accepts inline, end, or below. color="danger" styles a destructive action. Avoid nesting interactive controls inside a row rendered as a button.

import { Button } from 'twenty-ui/primitives/input';
import { ListItem } from 'twenty-ui/primitives/navigation';

type ContactRowProps = { onOpen: () => void };

export const ContactRow = ({ onOpen }: ContactRowProps) => (
  <ListItem
    description="Account owner"
    actions={
      <Button
        type="button"
        aria-label="Open Alex Morgan's profile"
        variant="ghost"
        size="sm"
        onClick={onOpen}
      >
        Open
      </Button>
    }
  >
    Alex Morgan
  </ListItem>
);

Labels

Use shortcutJoinLabel to customize the text between sequential shortcut steps. It defaults to then; an empty string removes the join text. The same prop is available on Dropdown item parts.

Props

The reference is generated from the public component types. Native div attributes and handlers are accepted, including accessible names and native events. Put button- or anchor-specific attributes on the element supplied through render. Both ref and the rendered element’s ref target the actual DOM root.

ReactNode

Trailing content, such as buttons, rendered after the content.

"auto" | "end"

default:"auto"

Keeps actions beside the content at every width when set to end. The default auto preserves responsive wrapping. Hidden end actions do not reserve width on devices without touch.

"always" | "hover"

default:"hover"

When trailing actions are visible: on hover and focus, or always.

boolean

default:"false"

Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item.

"danger" | "neutral"

default:"neutral"

Color of the text and icons. danger marks a destructive action.

ReactNode

Supporting text, placed according to descriptionPlacement.

"below" | "end" | "inline"

default:"inline"

Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.

boolean

default:"false"

Applies disabled styling only. Set native disabled behavior and accessible semantics on the button, link, or popup item owner.

ReactNode

Icon rendered after the content.

boolean

default:"false"

Applies highlighted styling without moving DOM focus or handling keyboard navigation.

boolean

default:"false"

Shows a chevron indicating that the item opens a submenu.

"check" | "checkbox" | "none"

default:"none"

Selection indicator: a check icon after the content or a checkbox before it.

Ref<HTMLElement>

Ref to the actual DOM root, including a composed native button or link.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ListItemState>

Composes the row with an element or render callback. The owner supplies interaction semantics, native attributes, and behavior.

boolean

default:"false"

Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner.

"accent" | "default"

default:"default"

Selection styling independent of description placement. default preserves indicator-based styling; accent fills selected rows with the accent background.

ShortcutDefinition

Keyboard shortcut keys displayed at the end of the row. Registering the shortcut is up to the application.

string

Text between sequential shortcut steps. Defaults to then; pass an empty string to omit it.

ReactNode

Icon rendered before the content.

Pass shortcut={['Mod', 'Enter']} for simultaneous keys or shortcut={[['G'], ['P']]} for successive presses. See Shortcut for nested combinations and the shared string formatter.

Developers

Apps

API

Self-Host

Contribute

UI Library

Overview

Usage

Anatomy

Multiline rows

Independent visual states

Independent controls

Action row

Navigation and explicit links

Native event policy

Application-owned drag and editor navigation

Settings row

Selection indicator

Picker rows

Single selection

Multiple selection

Slots

Labels

Props

​Overview

​Usage

​Anatomy

​Multiline rows

​Independent visual states

​Independent controls

​Action row

​Navigation and explicit links

​Popup item owner

​Native event policy

​Application-owned drag and editor navigation

​Settings row

​Selection indicator

​Picker rows

​Single selection

​Multiple selection

​Slots

​Labels

​Props

Overview

Usage

Anatomy

Multiline rows

Independent visual states

Independent controls

Action row

Navigation and explicit links

Popup item owner

Native event policy

Application-owned drag and editor navigation

Settings row

Selection indicator

Picker rows

Single selection

Multiple selection

Slots

Labels

Props