Skip to content

List

Get Ritla UI

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

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add list

    Also works with shadcn: npx shadcn@latest add @ritla/list

  2. Dependencies it brings

    @phosphor-icons/react

  3. Or 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

list.tsx
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.

EnglishMirroredArabic
LTR →

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.

EnglishMirroredArabic
LTR →

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.

EnglishMirroredArabic
LTR →

API reference

List

PropTypeDefaultDescription
aria-labelstringNoneThe list's name when the page has several.
childrenReactNodeNoneListItem or SwipeableListItem rows.

ListItem

PropTypeDefaultDescription
childrenReactNodeNoneFigma's Headline.
overlineReactNodeNoneFigma's Overline: a short line above the headline.
supportingTextReactNodeNoneFigma's Supporting text, below the headline.
leadingReactNodeNoneThe start element: an avatar, a flag or an image.
leadingIconIconComponentNoneAn icon in a 40px circle (Type = Icon).
trailingReactNodeNoneFigma's Show Tags: a tag or any node at the end.
hrefstringNoneMakes the row a link.
renderReactElementNoneA router link (<Link>) with the row's look.
onClickMouseEventHandlerNoneMakes the row a button.
disabledbooleanfalseFigma's State = Disabled. On a swipeable row: no swipe, and the ⋮ button is disabled.

SwipeableListItem

PropTypeDefaultDescription
leadingActionsSwipeAction[]NoneRevealed at the start by swiping toward the end (Swipe = Leading).
trailingActionsSwipeAction[]NoneRevealed at the end by swiping toward the start (Swipe = Trailing).
SwipeAction{ label, icon, tone?: "brand" | "warning" | "danger", onAction }NoneOne 88px action.
menubooleantrueA ⋮ button with the same actions, so swiping isn't the only way.
menuLabelstring"More actions"The ⋮ button's name; in the page language by default.
…ListItem propsNoneEvery 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 toUseWhy
Show messages, notifications or activityList itemEach row is a short story with a time and a summary.
Let people act on a row with a gesture on mobileSwipeable list itemFrequent actions sit one swipe away.
Compare amounts, dates and statuses across many recordsTableColumns make comparison and sorting easy.
Pick one option from a short setMenu, Select or RadioA 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: Short headline, detail belowPeople scan names, then read the amount and the time.
Don't: Everything in the headlineHeadlines wrap onto three lines, and the supporting text repeats them.

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.

Do: RTL variantThe avatar sits on the right and the text aligns right, in the Arabic fonts and line heights.
Don't: English variant with Arabic textThe avatar stays on the left and the text is set in the Latin fonts.

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.

KeyAction
TabTo the interactive rows and each swipeable row's ⋮ button.
EnterFollows the link, presses the row or opens the actions menu.

ARIA

  • The list is a ul and each row an li, 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 disabled button or an aria-disabled link 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-16 Medium, supporting text body-12, overline label-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.

  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space
  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)