ListItem represents a row in list-like surfaces with support for navigation (href) or imperative actions (onClick). Choosing the right mode preserves semantic HTML and predictable keyboard behavior—critical when list groups back secondary navigation in dispatch panels.
- Rows that primarily navigate to another screen or expand a detail pane.
- Simple actions that logically belong to the row (pin, star) without turning the whole row into a confusing hybrid.
- Single free-standing actions—use
Button for clarity.
- Data tables where sort, select, and resize matter—use
Table/DataTable rows.
- Rows that mix unrelated controls—split into structured layouts.
Navigation vs action mode should be mutually exclusive per row pattern; do not nest interactive controls that fight each other for events.
Primary label, optional description, optional leading/trailing slots, focus ring spanning the interactive region when appropriate.
- Use
formatMessage for labels; keep descriptions one line when possible.
- Truncate with tooltips only when full text is available to assistive tech.
- Loading rows should disable interaction or swap to skeletons—avoid click targets that no-op.
- Selected vs unselected styling must be per design system for active nav items.
- Do use
href when the row is navigation-first—supports Cmd/Ctrl+click and accessibility expectations.
- Do reserve
onClick for in-place actions when designers explicitly model that pattern.
- Don’t nest buttons inside a full-row link without careful event handling and accessibility review.
- Don’t use list items as table replacements for wide data grids.
- Ensure focus visibility and roles match whether the row is a link or button.
- Provide descriptive names; decorative icons must not replace text.
