ListItem

Compose consistent rows with icons, descriptions, indicators, and actions.

ListItem supplies the visual layout shared by list and menu rows. Use Menu or Select when you need their selection and keyboard behavior.

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 supporting icons at either end of the row content.
description	Optional	Adds supporting text inline or at the end, according to descriptionPlacement.
actions	Optional	Adds trailing content, such as a separately focusable action.
indicator, hotkeys, hasSubmenu	Optional	Configure built-in selection marks, shortcut hints, and the submenu indicator.

The row supplies layout. Use render to choose its element and semantics. For a row with independent action buttons, keep the row itself non-interactive so those buttons remain separate controls.

Action row

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

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

export const DuplicateAction = ({ onDuplicate }: DuplicateActionProps) => (
  <ListItem
    render={<button type="button" />}
    startIcon={<IconCopy aria-hidden />}
    description="Create a copy"
    onClick={onDuplicate}
  >
    Duplicate
  </ListItem>
);

The default element is a div. Use render to give an interactive row appropriate semantics, such as a button or link. hotkeys displays shortcut hints; your application must register the shortcuts.

Settings row

Use SettingsRow for a labeled switch row. It composes ListItem and Switch, manages their accessible association, and applies disabled behavior to both.

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>
  );
};

selected, focused, and disabled control row styling. The check and checkbox indicators are visual; use a real Checkbox for a form control. When using a disabled button or link through render, also supply the element’s appropriate disabled behavior and semantics.

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 and share the row’s click handler.

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" />}
          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. Supply disabled to both the row and its rendered native button to prevent activation and remove it from the tab order.

Slots

Use startIcon and endIcon for icons, description for supporting text, actions for trailing content, and hasSubmenu for a submenu indicator. descriptionPlacement accepts inline or end. 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>
);

Props

The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.

actions · ReactNode

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

actionsVisibility · "always" | "hover" · default: "hover"

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

color · "danger" | "neutral" · default: "neutral"

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

description · ReactNode

Supporting text, placed according to descriptionPlacement.

descriptionPlacement · "end" | "inline" · default: "inline"

Where the description renders: inline after the content or at the end of the row.

disabled · boolean · default: "false"

Prevents clicks and applies the disabled style.

endIcon · ReactNode

Icon rendered after the content.

focused · boolean · default: "false"

Applies the highlighted style, for example to the focused item of a list.

hasSubmenu · boolean · default: "false"

Shows a chevron indicating that the item opens a submenu.

hotkeys · string[]

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

indicator · "check" | "checkbox" | "none" · default: "none"

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

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

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

selected · boolean · default: "false"

Whether the item is selected. Shows the check or checkbox indicator when indicator is set.

startIcon · ReactNode

Icon rendered before the content.