ListGroup

A flexible and interactive component for displaying grouped lists with support for icons, badges, links, buttons, active/disabled states, striped and flush variants, and horizontal layouts. Useful for navigation menus, settings, dashboards, and any grouped content.

---

Import

import { ListGroup } from '@odyssee/components';
// Helpers: ListGroup.Link, ListGroup.Button, ListGroup.Flush, ListGroup.Horizontal

---

Examples

Basic List Group

Code Éditable

Résultat

---

List Group with Icons

Code Éditable

Résultat

---

List Group with Badges

Code Éditable

Résultat

---

List Group as Links

Code Éditable

Résultat

---

List Group as Buttons

Code Éditable

Résultat

---

Striped List Group

Code Éditable

Résultat

---

Flush Variant (No Borders)

Code Éditable

Résultat

---

Horizontal Variant (Responsive)

Code Éditable

Résultat

---

Active and Disabled States

Code Éditable

Résultat

---

Props Table

ListGroup Props

Prop	Type	Default	Description
items	(string | ListGroup.Item)[]	— (required)	Array of items (strings or objects with content, icon, badge, etc.).
variant	"default" | "flush" | "horizontal"	"default"	Visual style of the group: bordered, flush (no borders), or horizontal layout.
as	"li" | "button" | "a"	"li"	Render items as <li>, <button>, or <a>.
striped	boolean	false	Alternating background for items (default variant only).
noGutters	boolean	false	Remove horizontal padding from items.
size	"sm" | "md" | "lg"	"md"	Size of the items.
activeIndex	number | Signal<number>	—	Index of the active item (overrides per-item active).
onItemClick	(item: ListGroup.Item | string, index: number) => void	—	Callback when an item is clicked (button or li mode).
className	string	—	Additional CSS classes for the container.
id	string	auto-gen	HTML id attribute.
style	string	—	Inline styles.

ListGroup.Item

Field	Type	Description
id	string	Optional unique identifier.
content	string | HTMLElement	The content of the item.
icon	HTMLElement | string	Optional icon to display before the content.
badge	string | number	Optional badge (number or label) to display.
badgeColor	Color	Badge color (primary, secondary, success, etc.).
href	string	Link URL (for link variant).
active	boolean	Mark item as active.
disabled	boolean	Mark item as disabled.
onClick	(event: Event) => void	Item-specific click handler.

---

Helper Components

• ListGroup.Link: Renders items as <a> links.
• ListGroup.Button: Renders items as <button>.
• ListGroup.Flush: Flush variant (no borders, uses dividers).
• ListGroup.Horizontal: Responsive horizontal layout.

---

Implementation Notes

• Variants:
  • "default": Bordered, stacked list (with optional stripes).
  • "flush": No borders, uses dividers.
  • "horizontal": Responsive row layout on larger screens.
• Rendering:
  • Use as="a" for navigation, as="button" for actions, or default for static lists.
• Icons & Badges:
  • Each item can have an icon and/or a badge (with color).
• Active/Disabled:
  • Items can be marked as active or disabled (visually and for interaction).
• Helpers:
  • Use helper components for common variants and less boilerplate.
• Composition:
  • Items can be strings (simple) or objects (for advanced formatting).

---

Accessibility

• Uses semantic <ul>, <li>, <a>, and <button> elements as appropriate.
• Disabled items are not focusable or clickable.
• Active items are visually distinct.
• Badges and icons are decorative; ensure the main content is descriptive.
• For navigation, add ARIA roles as needed in your context.

---

Best Practices

• Use for navigation menus, settings, dashboards, or grouped actions.
• Prefer semantic and descriptive content for accessibility.
• Use icons and badges to enhance clarity and context.
• Use the horizontal variant for tabs or responsive navigation.
• Combine with cards, sidebars, or sections for richer UIs.

---

Related

• Pulse Framework
• Tailwind CSS List Utilities
• MDN: <ul> and <li> elements

---