List Component

The List component is a flexible UI primitive for simple lists, icon lists, drawer navigation, dropdown menus, nested submenus, and tree-style structures. Items can render as static content, buttons, or links, with optional leading and trailing content.

Use variant, density, and size for visual tone, href or onClick for actions, and subItems with defaultExpandedIds for submenu-style navigation. Bullets are off by default so lists drop cleanly into drawers, sidebars, and menus.

Import Component From Library

javascript

1import { List } from "@neuctra/ui";

Basic Usage Code

Start with a normal content list. Static rows render as content, while rows with links, clicks, or children become interactive.

jsx

1import { List } from "@neuctra/ui";
2
3function BasicExample() {
4  const items = [
5    { text: "First item" },
6    { text: "Second item" },
7    {
8      text: "Third item",
9      subItems: [
10        { text: "Nested A" },
11        { text: "Nested B" }
12      ]
13    }
14  ];
15
16  return <List items={items} />;
17}

Basic Example

First item
Second item

Navigation Drawer

Workspace

Drawer friendly navigation

Dropdown Menu List

List Types And Markers

Inline Navigation

Setup Steps

Install dependencies
Configure project
Run application

Cards And Icon Lists

NotificationsUser alerts and product updatesLive
SecurityAudit logs, permissions, and sessions

Tree View

First item
Second item

Item Structure

Each item supports static content, link rows, button rows, separators, metadata, and nested submenus.

tsx

1type ListItemType = {
2  id?: string | number;
3  text?: ReactNode;
4  label?: ReactNode;
5  description?: ReactNode;
6  icon?: ReactNode;
7  leading?: ReactNode;
8  trailing?: ReactNode;
9  badge?: ReactNode;
10  shortcut?: ReactNode;
11
12  href?: string;
13  target?: React.HTMLAttributeAnchorTarget;
14  onClick?: (event, item) => void;
15
16  subItems?: ListItemType[];
17  items?: ListItemType[];
18  active?: boolean;
19  disabled?: boolean;
20  danger?: boolean;
21  separator?: boolean;
22  hidden?: boolean;
23};

List Props

Prop	Type	Default	Description
`title`	ReactNode	-	Optional heading above the list.
`titleIcon`	ReactNode	-	Icon rendered before the title.
`description`	ReactNode	-	Supporting text under the title.
`items`	ListItemType[]	-	Main data source for rows and nested rows.
`type`	"unordered" \| "ordered" \| "inline"	"unordered"	Controls list layout.
`variant`	"default" \| "nav" \| "menu" \| "card" \| "ghost"	"default"	Changes row styling for content lists, navs, menus, and cards.
`size`	"sm" \| "md" \| "lg"	"md"	Controls row text scale.
`density`	"compact" \| "normal" \| "comfortable"	"normal"	Controls row padding.
`nestedMode`	"always" \| "collapse"	"collapse"	Controls whether nested items are always visible or collapsible.
`bulletVariant`	"dot" \| "line" \| "number" \| "none"	"dot"	Custom marker style when showBullets is enabled.
`showTree`	boolean	false	Shows hierarchy connector lines.
`showBullets`	boolean	false	Shows custom markers when rows have no icon.
`showDividers`	boolean	false	Adds borders between rows.
`interactive`	boolean	true	Enables clickable row behavior.
`fullWidth`	boolean	true	Makes the root fill available width.
`disabled`	boolean	false	Disables all list items.
`activeItemId`	string \| number	-	Controlled active item id.
`defaultActiveItemId`	string \| number	-	Initial active item id for uncontrolled usage.
`onActiveChange`	(id, item) => void	-	Called when a selectable item is activated.
`expandedIds`	Array<string \| number>	-	Controlled expanded submenu ids.
`defaultExpandedIds`	Array<string \| number>	[]	Initial expanded submenu ids for uncontrolled usage.
`onExpandedChange`	(ids) => void	-	Called when collapsible submenu state changes.
`role`	string	-	Role applied to the ul/ol element.
`ariaLabel`	string	-	Accessible label for the list element.
`emptyState`	ReactNode	"No items to show."	Rendered when items are empty.
`linkComponent`	ElementType	"a"	Custom link component for routers such as Link.
`renderItem`	(params) => ReactNode	-	Full custom row renderer with active, expanded, toggle, and select helpers.

ListItemType Props

Prop	Type	Default	Description
`id`	string \| number	-	Stable id for active and expanded state.
`text`	ReactNode	-	Primary row label. Legacy-friendly alias.
`label`	ReactNode	-	Primary row label alternative.
`description`	ReactNode	-	Secondary text under the label.
`icon`	ReactNode	-	Leading icon.
`leading`	ReactNode	-	Leading custom content. Falls back to icon.
`trailing`	ReactNode	-	Trailing custom content.
`badge`	ReactNode	-	Small badge beside the row label.
`shortcut`	ReactNode	-	Keyboard shortcut hint.
`href`	string	-	Renders the item as a link.
`target`	HTMLAttributeAnchorTarget	-	Anchor target, such as _blank.
`rel`	string	auto	Anchor rel. _blank defaults to noreferrer.
`download`	boolean \| string	-	Anchor download attribute.
`onClick`	(event, item) => void	-	Click handler for the row.
`subItems`	ListItemType[]	-	Nested children.
`items`	ListItemType[]	-	Nested children alias.
`expanded`	boolean	-	Per-item controlled expanded state.
`defaultExpanded`	boolean	-	Initial expanded state for the item.
`collapsible`	boolean	true in collapse mode	Controls the submenu chevron behavior.
`active`	boolean	false	Marks the item active.
`disabled`	boolean	false	Disables the item.
`danger`	boolean	false	Applies destructive styling.
`separator`	boolean	false	Renders a divider row.
`hidden`	boolean	false	Excludes the item from rendering.
`title`	string	-	Native title attribute.
`ariaLabel`	string	-	Accessible label for the row.
`role`	string	-	Role applied to the li element.
`className / style`	string / CSSProperties	-	Per-item wrapper customization.
`contentClassName / contentStyle`	string / CSSProperties	-	Per-item clickable/content row customization.
`iconClassName / iconStyle`	string / CSSProperties	-	Per-item icon override, merged with the list's iconClassName/iconStyle.
`textClassName / textStyle`	string / CSSProperties	-	Per-item label override, merged with the list's textClassName/textStyle.
`descriptionClassName / descriptionStyle`	string / CSSProperties	-	Per-item description text override.
`badgeClassName / badgeStyle`	string / CSSProperties	-	Per-item badge override, merged with the list's badgeClassName/badgeStyle.
`subListClassName / subListStyle`	string / CSSProperties	-	Per-item nested <ul> override, merged with the list's subListClassName/subListStyle.

Styling Hooks

Class Prop	Style Prop	Target
`className`	style	Root wrapper.
`headerClassName`	headerStyle	Title and description wrapper.
`listClassName`	listStyle	ul/ol element.
`itemClassName`	itemStyle	li wrapper.
`itemContentClassName`	itemContentStyle	Clickable row/content wrapper.
`titleClassName`	titleStyle	List heading.
`descriptionClassName`	descriptionStyle	List heading description.
`bulletClassName`	bulletStyle	Custom bullet marker.
`textClassName`	textStyle	Item label text.
`iconClassName`	iconStyle	Title and item icons.
`badgeClassName`	badgeStyle	Item badge.
`shortcutClassName`	shortcutStyle	Shortcut kbd element.
`trailingClassName`	trailingStyle	Trailing item content.
`subListClassName`	subListStyle	Nested ul element.
`separatorClassName`	separatorStyle	Separator row.
`chevronClassName`	—	Expand/collapse chevron icon.
`externalIconClassName`	—	External-link icon on href items.
`emptyStateClassName`	—	Empty state message container.

Common Mistakes

<List primaryColor="#f00" />

This prop does not exist. Use semantic theme classes or the class/style hooks.

{ text: 'Team', subItems: [...] }

In collapse mode, nested items start collapsed unless you use defaultExpanded, defaultExpandedIds, or nestedMode="always".

<List variant="nav" defaultExpandedIds={["team"]} />

Use stable item ids for active and expanded navigation state.

Pro Tips

Use variant="nav" inside drawers and sidebars.
Use variant="menu" with density="compact" for dropdown menus.
Prefer stable id values when using active or expanded state.
Pass a router Link through linkComponent when using client-side navigation.
Use renderItem only when class and item props are not enough.

Frequently Asked Questions

How do I install and import the List component?

Install the @neuctra/ui package, then import it with: import { List } from "@neuctra/ui";

What variants and sizes does List support?

List supports variants: default, nav, menu, card, ghost and sizes: sm, md, lg. Use the variant and size props to switch between them, or pass a className to layer on custom Tailwind CSS classes.

Is the List component accessible?

List is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.