ListItem

Panoramica

ListItem fornisce il layout visivo condiviso dalle righe di elenchi e menu. Per impostazione predefinita, esegue il rendering di un div per i contenuti passivi. Usa ListItemButton per le normali righe di azione. Componi ListItem con un’ancora per la navigazione o con un elemento proprietario semantico personalizzato quando necessario. Utilizza Dropdown o Select quando ti serve un contenitore completo per popup o selezioni.

Utilizzo

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

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

Anatomia

ListItem espone slot di contenuto tramite le props. Questi slot organizzano il contenuto all’interno di una riga; non sono componenti esportati separatamente.

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

Slot	Requisito	Scopo
`children`	Obbligatorio per un’etichetta di riga visibile	Fornisce il testo principale.
`startIcon`, `endIcon`	Facoltativo	Aggiunge icone, avatar, metadati o controlli indipendenti a entrambe le estremità.
`description`	Facoltativo	Aggiunge contenuto di supporto in linea, sotto l’etichetta o alla fine.
`azioni`	Facoltativo	Aggiunge contenuto finale, ad esempio un’azione attivabile separatamente.
`indicator`, `shortcut`, `hasSubmenu`	Facoltativo	Configura i contrassegni di selezione integrati, i suggerimenti per le scorciatoie e l’indicatore del sottomenu.

La riga fornisce il layout. render accetta un elemento o una callback che riceve props nativi e stato visivo. Distribuisci tali props sulla radice effettiva quando usi una callback. Gli attributi nativi, i gestori di eventi, className, style e ref raggiungono tale radice. Per una riga con pulsanti di azione indipendenti, mantieni la riga stessa non interattiva affinché tali pulsanti rimangano controlli separati.

Righe su più righe

Imposta descriptionPlacement="below" per posizionare il contenuto di supporto sotto l’etichetta. Il titolo mantiene il comportamento di troncamento esistente e il contenuto di supporto va a capo in base alla larghezza disponibile. Il posizionamento predefinito inline e il posizionamento end mantengono il loro aspetto esistente.

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

Per anteprime più brevi, passa un componente Text con truncate o lineClamp come description. Il contenuto personalizzato controlla il proprio layout e le proprie etichette accessibili.

Stati visivi indipendenti

Tutto lo stato visivo appartiene al chiamante. active identifica la riga aperta o corrente senza selezionarla. selected rappresenta la selezione e focused rappresenta un’evidenziazione della navigazione tramite tastiera senza spostare il focus DOM. active applica lo sfondo della riga corrente. Imposta selectionAppearance="accent" per un riempimento accentato sulle righe selezionate, indipendentemente dalla posizione della descrizione. L’aspetto predefinito mantiene lo stile di selezione esistente basato su indicatori. focused applica lo sfondo evidenziato condiviso, incluso quando un proprietario lo usa per l’evidenziazione del puntatore. Il contorno visibile del focus segue l’effettivo focus della tastiera sulla radice o sui relativi controlli. Queste props non aggiungono stati accessibili. Fornisci aria-current, aria-selected o lo stato checked di un controllo al proprietario semantico appropriato. L’effettivo focus della tastiera mantiene anche il contorno nativo visibile del focus.

Controlli indipendenti

Mantieni la radice div predefinita quando una riga contiene una vera casella di controllo o pulsanti di azione indipendenti. Usa startIcon per la casella di controllo e actions per i pulsanti. L’indicator decorativo non è necessario quando una vera casella di controllo mostra già la selezione.

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

La selezione e l’apertura sono interazioni separate. L’applicazione gestisce la propagazione degli eventi e qualsiasi attivazione delle righe o criterio relativo alla tastiera. ListItem.disabled modifica solo l’aspetto; passa disabled a ogni controllo reale per impedirne l’attivazione. Il comportamento esistente di visibilità delle azioni si applica alle righe su più righe: actionsVisibility="hover" mostra le azioni al passaggio del mouse o al focus all’interno della riga e le mantiene visibili sui dispositivi touch. Impostalo su always per azioni persistenti, incluso quando è aperto un popup gestito dal chiamante. Con larghezze delle righe pari o inferiori a 480px, le azioni su più righe vengono spostate sulla propria riga e vanno a capo secondo necessità.

Riga di azione

Usa ListItemButton per abbinare lo stile della riga all’interazione nativa del pulsante. Passa disabled una volta per controllare sia l’aspetto sia l’attivazione.

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

Un proprietario di pulsante personalizzato può comunque comporre ListItem tramite render. Tale proprietario fornisce focus nativo, attivazione con Invio e Spazio e comportamento disabilitato. ListItem.disabled fornisce solo lo stile visivo corrispondente. shortcut visualizza suggerimenti; la tua applicazione registra le scorciatoie.

Navigazione e link espliciti

Passa un’ancora tramite render quando l’intera riga effettua la navigazione. Inserisci gli attributi dell’ancora, inclusi href, target e rel, su tale elemento.

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

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

Le etichette stringa restano testo, incluse le stringhe con formato URL. ListItem non crea link. Per collegare una parte di una riga non interattiva, fornisci un’ancora come contenuto di proprietà del chiamante. Mantieni tale riga come div per evitare link o pulsanti annidati. Le etichette stringa mantengono il troncamento e il tooltip di overflow; il contenuto personalizzato può usare OverflowingTextWithTooltip con un’ancora renderizzata esplicita. I link non hanno un attributo disabled nativo. Se una destinazione non è disponibile, il proprietario del link deve fornire la semantica appropriata, l’ordine di tabulazione e la politica di navigazione. Assegnargli lo stile solo con ListItem.disabled non impedisce la navigazione. Utilizza Dropdown.ActionItem o Dropdown.OptionItem all’interno del relativo contenitore popup. Queste parti compongono già il layout di ListItem ed espongono i relativi slot visivi. Il proprietario popup fornisce ruoli, focus, navigazione da tastiera, attivazione e comportamento disabilitato.

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

Politica degli eventi nativi

ListItem inoltra oggetti e gestori di eventi nativi. I clic si propagano normalmente, inclusi i clic sui controlli di azione finali. Definisci qualsiasi confine intenzionale sul proprietario interattivo o sul gestore del chiamante.

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

Il chiamante gestisce inoltre qualsiasi politica preventDefault(), come impedire la navigazione di un link. Passare onClick non aggiunge un ruolo, non rende un div utilizzabile da tastiera né modifica la propagazione.

Trascinamento gestito dall’applicazione e navigazione dell’editor

Componi righe riordinabili con ListItem all’interno dell’host di trascinamento della tua applicazione. Inserisci gli attributi e gli ascoltatori di trascinamento dell’host sulla relativa maniglia e passa la maniglia o l’impugnatura tramite startIcon. Mantieni controlli indipendenti di visibilità, modifica ed eliminazione in actions. L’host di trascinamento gestisce il riordinamento tramite puntatore e tastiera, il trascinamento disabilitato e le etichette accessibili della maniglia. Per i suggerimenti dell’editor, mantieni la listbox esistente dell’editor e il proprietario dell’opzione attiva. Esegui il rendering di ogni ListItem con role="option" e aria-selected, e usa focused per l’aspetto della riga attiva. L’editor gestisce la navigazione con le frecce e l’attivazione con Invio mentre lo stato attivo rimane nella superficie di modifica. Impedisci le modifiche dello stato attivo al pointer-down quando l’editor le richiede e gestisci la selezione tramite puntatore nel gestore di riga dell’applicazione. Per i suggerimenti in una pagina Dropdown, usa Dropdown.OptionItem o Dropdown.ActionItem affinché la pagina gestisca la navigazione e l’attivazione. Non aggiungere un secondo gestore per Invio o Spazio a un proprietario che si attiva già dalla tastiera.

Riga delle impostazioni

Usa SettingsRow per una riga di interruttore con etichetta. Compone ListItem e Switch, gestisce la loro associazione accessibile e utilizza lo stato disabilitato dell’interruttore per l’aspetto della riga.

Indicatore di selezione

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 e disabled controllano indipendentemente lo stile della riga. Non registrano azioni, non spostano il focus DOM, non aggiungono ruoli o stati accessibili e non sopprimono eventi. Gli indicatori check e checkbox sono decorativi; usa un vero Checkbox per un controllo del modulo. Imposta aria-pressed, aria-selected o altre semantiche di stato sul proprietario che ne ha bisogno.

Righe del selettore.

La selezione appartiene al componente padre. ListItem non ha uno stato di selezione non controllato: passa selected e aggiornalo da onClick. Usa indicator="check" per una singola scelta e indicator="checkbox" per scelte multiple. Entrambi gli indicatori sono decorativi; il proprietario interattivo gestisce l’attivazione. In una listbox esistente, passa role="option" e aria-selected e mantieni la gestione dello stato attivo e dei tasti freccia nella listbox. Per un widget di selezione completo, usa Select. I pulsanti di selezione indipendenti possono usare aria-pressed, come in questi esempi.

Selezione singola

Inserisci un Avatar in startIcon per identificare un record. Usa description per il testo di supporto e descriptionPlacement="end" per un valore finale.

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

Selezione multipla

Componi Tag come contenuto della riga per i valori con tag oppure inserisci ColorSample in startIcon per una scelta di colore. Una riga può contenere anche testo semplice o un 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>
  );
};

L’indicatore della casella di controllo non è un controllo del modulo e non invia un valore. Usa Checkbox quando hai bisogno della partecipazione al modulo. Imposta disabled nativo sul pulsante renderizzato per impedire l’attivazione e rimuoverlo dall’ordine di tabulazione. Passa anche ListItem.disabled per il suo aspetto visivo.

Slot

Usa startIcon e endIcon per icone o contenuti gestiti dal chiamante, description per il testo di supporto, actions per il contenuto finale e hasSubmenu per un indicatore di sottomenu. descriptionPlacement accetta inline, end o below. color="danger" applica lo stile a un’azione distruttiva. Evita di nidificare controlli interattivi all’interno di una riga resa come pulsante.

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

Etichette

Usa shortcutJoinLabel per personalizzare il testo tra i passaggi sequenziali delle scorciatoie. Per impostazione predefinita è then; una stringa vuota rimuove il testo di collegamento. La stessa prop è disponibile nelle parti degli elementi Dropdown.

Props

Il riferimento viene generato dai tipi di componenti pubblici. Gli attributi e i gestori div nativi sono accettati, inclusi nomi accessibili ed eventi nativi. Inserisci gli attributi specifici del pulsante o dell’ancora sull’elemento fornito tramite render. Sia ref sia il ref dell’elemento renderizzato puntano alla radice DOM effettiva.

ReactNode

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

"auto" | "end"

predefinito:"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"

predefinito:"hover"

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

boolean

predefinito:"false"

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

"danger" | "neutral"

predefinito:"neutral"

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

ReactNode

Supporting text, placed according to descriptionPlacement.

"below" | "end" | "inline"

predefinito:"inline"

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

boolean

predefinito:"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

predefinito:"false"

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

boolean

predefinito:"false"

Shows a chevron indicating that the item opens a submenu.

"check" | "checkbox" | "none"

predefinito:"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

predefinito:"false"

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

"accent" | "default"

predefinito:"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.

Passa shortcut={['Mod', 'Enter']} per tasti simultanei o shortcut={[['G'], ['P']]} per pressioni successive. Consulta Shortcut per le combinazioni annidate e il formattatore di stringhe condiviso.

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Panoramica

Utilizzo

Anatomia

Righe su più righe

Stati visivi indipendenti

Controlli indipendenti

Riga di azione

Navigazione e link espliciti

Politica degli eventi nativi

Trascinamento gestito dall’applicazione e navigazione dell’editor

Riga delle impostazioni

Indicatore di selezione

Righe del selettore.

Selezione singola

Selezione multipla

Slot

Etichette

Props

​Panoramica

​Utilizzo

​Anatomia

​Righe su più righe

​Stati visivi indipendenti

​Controlli indipendenti

​Riga di azione

​Navigazione e link espliciti

​Proprietario dell’elemento popup

​Politica degli eventi nativi

​Trascinamento gestito dall’applicazione e navigazione dell’editor

​Riga delle impostazioni

​Indicatore di selezione

​Righe del selettore.

​Selezione singola

​Selezione multipla

​Slot

​Etichette

​Props

Panoramica

Utilizzo

Anatomia

Righe su più righe

Stati visivi indipendenti

Controlli indipendenti

Riga di azione

Navigazione e link espliciti

Proprietario dell’elemento popup

Politica degli eventi nativi

Trascinamento gestito dall’applicazione e navigazione dell’editor

Riga delle impostazioni

Indicatore di selezione

Righe del selettore.

Selezione singola

Selezione multipla

Slot

Etichette

Props