List
Rows of people, messages or settings: a headline with an overline and supporting text, an avatar or icon at the start, a tag at the end. The swipeable row reveals actions when swiped.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add listAlso works with shadcn:
npx shadcn@latest add @ritla/listDependencies it brings
@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { List, ListItem } from "@/components/ui/list";<List aria-label="Team"> <ListItem leading={<Avatar name="Omar Haddad" size="sm" decorative />} supportingText="Product designer"> Omar Haddad </ListItem></List>Examples
Icon and overline
leadingIcon puts the icon in a 40px circle. These rows are buttons (onClick), so they get the hover fill.
Swipeable row
Swipe toward the end to archive, toward the start to snooze or delete. Start and end follow the reading direction. The ⋮ button lists the same actions for keyboards, screen readers and mice.
Links and a static row
href or render={<Link />} makes a row a link. A row with neither a link nor onClick is static, with no hover fill.
A disabled row
disabled turns the text to the disabled color, fades the leading and trailing nodes to 48% and drops the hover. A button row becomes a disabled button, and a link row loses its target. Say why in the supporting text.
API reference
List
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label | string | None | The list's name when the page has several. |
children | ReactNode | None | ListItem or SwipeableListItem rows. |
ListItem
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Headline. |
overline | ReactNode | None | Figma's Overline: a short line above the headline. |
supportingText | ReactNode | None | Figma's Supporting text, below the headline. |
leading | ReactNode | None | The start element: an avatar, a flag or an image. |
leadingIcon | IconComponent | None | An icon in a 40px circle (Type = Icon). |
trailing | ReactNode | None | Figma's Show Tags: a tag or any node at the end. |
href | string | None | Makes the row a link. |
render | ReactElement | None | A router link (<Link>) with the row's look. |
onClick | MouseEventHandler | None | Makes the row a button. |
disabled | boolean | false | Figma's State = Disabled. On a swipeable row: no swipe, and the ⋮ button is disabled. |
SwipeableListItem
| Prop | Type | Default | Description |
|---|---|---|---|
leadingActions | SwipeAction[] | None | Revealed at the start by swiping toward the end (Swipe = Leading). |
trailingActions | SwipeAction[] | None | Revealed at the end by swiping toward the start (Swipe = Trailing). |
SwipeAction | { label, icon, tone?: "brand" | "warning" | "danger", onAction } | None | One 88px action. |
menu | boolean | true | A ⋮ button with the same actions, so swiping isn't the only way. |
menuLabel | string | "More actions" | The ⋮ button's name; in the page language by default. |
… | ListItem props | None | Every ListItem prop. |
Usage guidelines
A list shows records that are each read on their own, top to bottom. List, table or cards, the parts of a list item, writing its text, swipe actions, states and loading, how it mirrors in Arabic, and the checks before handoff.
1. List, table or cards
Use a list when each record is read on its own, top to bottom: a message, a notification, a contact, a payment. When people compare the same fields across records, use a table. When items are visual, use cards.
| You need to | Use | Why |
|---|---|---|
| Show messages, notifications or activity | List item | Each row is a short story with a time and a summary. |
| Let people act on a row with a gesture on mobile | Swipeable list item | Frequent actions sit one swipe away. |
| Compare amounts, dates and statuses across many records | Table | Columns make comparison and sorting easy. |
| Pick one option from a short set | Menu, Select or Radio | A list item is content, not a choice control. |
2. Parts of a List item
A leading element, an overline, a headline, supporting text and a trailing Tag. Only the headline is required. Use Avatar for people, Icon for events and objects, and Empty to keep the text aligned in rows with nothing to show.
Headline first, detail second
A payments activity list.
Do
- Use the overline for time or category: Today, 09:41.
- Make the headline the one thing people scan for.
- Use supporting text for the detail, in one or two lines.
- Use the trailing Tag for a count or a status.
- Pick one leading type per list, or Empty to keep text aligned.
Don't
- Repeat the headline in the supporting text.
- Put a sentence in the headline; it wraps and pushes the list down.
- Leave some rows without a leading element next to rows with one.
- Show a Tag on every row; it stops meaning anything.
3. Writing list text
Lists are scanned, not read. Start each headline with the word people look for, keep it to one line, and move everything else to the supporting text. Use the same pattern in every row.
Do
- Start with the name, title or event.
- Keep headlines to one line, and supporting text to two.
- Use one time format in the list: Today, Yesterday, then a date.
- Use sentence case and no end punctuation in headlines.
Don't
- Start headlines with filler: You have received…
- Mix full sentences and fragments in one list.
- Show raw IDs where people expect names.
4. Swipe actions
Swipeable list item reveals actions behind the row. Leading shows one positive action, such as Mark as read. Trailing shows up to two actions, with Delete at the far end. Swipes are hidden, so every swiped action must also be reachable another way.
Do
- Keep one leading action and up to two trailing actions.
- Color by meaning: Brand for positive, Warning for Archive or Snooze, Danger for Delete.
- Give every action an icon and a short label.
- Offer the same actions in a row menu or on the detail screen.
- Offer Undo in a Toast after Delete or Archive.
Don't
- Hide an action only behind a swipe.
- Put Delete on the leading side, where a quick swipe triggers it.
- Use swipes on desktop, where people can't swipe; show a row menu.
- Add a third trailing action.
5. States, loading and long lists
The whole row is one target: tapping it opens the record. Use Hovered on pointer devices. Show Skeleton rows while loading and an Empty state when there is nothing to show. Load long lists in pages or as people scroll.
Do
- Make the whole row open the record.
- Show Skeleton rows that match the row height while loading.
- Show an Empty state with a next step when the list is empty.
- Group long lists by day with a section header.
Don't
- Put a separate button in the row for the main action.
- Show a spinner in place of the whole list.
- Load thousands of rows at once.
6. Arabic and RTL
Use the RTL variant in Arabic lists. The leading element moves to the right, the Tag to the left, and swipe sides mirror: the leading action is revealed from the right. Times, amounts and phone numbers inside a row still read left to right.
Rows start on the right
A payments activity list in Arabic.
Before handoff
- Every row follows the same pattern and time format.
- Swipe actions are also in a menu or on the detail screen.
- Loading, empty and long-list behavior are designed.
- Arabic lists use the RTL variant.
- Desktop has row menus instead of swipes.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Tab | To the interactive rows and each swipeable row's ⋮ button. |
| Enter | Follows the link, presses the row or opens the actions menu. |
ARIA
- The list is a
uland each row anli, so screen readers announce the count. - An avatar next to the name is
decorative, so the name isn't read twice. - A disabled row is a
disabledbutton or anaria-disabledlink with no target, so it is announced as unavailable and can't be activated. Disabled text is exempt from the contrast minimum, so state the reason plainly. - Swiping is never the only way: the ⋮ button lists the same actions. Without it (
menu={false}) the action buttons are focusable and the row opens when one gets focus. - An open row closes on a tap or focus outside it.
Do
- List markup, each row one list item.
- Each row is one link or button, named by its headline.
- Swipe actions are named actions, and in a menu too.
- Rows at least 48 px tall.
- Name leading icons only when they add meaning.
Don't
- Nest several buttons inside one row link.
- Rely on the color of a swipe action to explain it.
Arabic and RTL notes
Mirrors
- The avatar or icon sits on the right; the tag and ⋮ button on the left.
- Swiping follows the reading direction: in Arabic a swipe to the left reveals the start actions (on the right), a swipe to the right the end actions.
Does not mirror
- The action icons (archive, clock, trash) and avatars.
- Numerals
- Numbers in the text are as you pass them; format them with
formatNumber. - Arabic typography
- Headline
body-16Medium, supporting textbody-12, overlinelabel-12. Rows are at least 70px, so taller Arabic text grows them instead of clipping. - Mixed-direction text
- Wrap names in another language inside Arabic text in
<bdi>.
Do
- The RTL variant for every row in an Arabic list.
- Mirror the swipe sides: leading is on the right in Arabic.
- Keep times and amounts left to right inside Arabic text.
- Write Arabic headlines natively.
Don't
- Arabic text in the English variant.
- Keep the English swipe sides in an Arabic list.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)