List

React List components are used to display a collection of related items. They are commonly used for navigation menus, settings panels, item groups, and structured content lists.

This List component is built with React and styled using Tailwind CSS. It supports vertical and horizontal layouts, dividers, and active item states.

Installation

npx @tailgrids/cli add list

Usage

Import the component and render list items as children.

import { List } from "@/registry/core/list";

export default function Example() {
  return (
    <List>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
    </List>
  );
}

Examples

Vertical List

Use the vertical layout for stacked navigation or menus.

Note: Vertical lists have a max width of 228px (14.25rem).

Horizontal List

Use the horizontal layout for inline navigation or filters.

Note: Horizontal lists have a max width of fit-content.

Without Dividers

You can remove dividers when visual separation is not needed. Dividers can be hidden with the hideDividers prop.

With Active State

Mark an item as active to indicate the current selection.

Note: Active items are styled with primary background and text color. Active state is communicated via data-active attribute.

With Icons

Add icons to list items for visual interest and better clarity.

With Badges

Use badges with icons to add more context and information to your list items.

Note: Counts with data-type="count" are automatically positioned with ml-auto. Icons automatically inherit the current text color.

Ordered and Unordered Lists

Create traditional ordered (numbered) and unordered (bullet) lists.

With Inputs

Integrate checkboxes or radio buttons for selectable list items.

User List

Display user information with avatars, names, emails, and status indicators.

API Reference

List

Extends ul element props.

List Item

Use standard <li> elements as children with optional data attributes:

Accessibility

• Uses semantic <ul> and <li> elements
• Active state is communicated via data-active attribute
• Hover states provide clear visual feedback and apply to all list items by default
• Keyboard accessible when used with interactive elements
• Icons inherit text color for consistent styling