# List Group

> List groups are a flexible component for displaying a series of content. Modify and extend them to support just about any content within.

Source: https://bootstrap-svelte.vercel.app/components/list-group — part of the Bootstrap Svelte documentation (index: https://bootstrap-svelte.vercel.app/llms.txt).

## Basic Example

The most basic list group is an unordered list with list items:

- An item
- A second item
- A third item
- A fourth item
- And a fifth one

```html
<ListGroup.Root>
    <ListGroup.Item>An item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
    <ListGroup.Item>A fourth item</ListGroup.Item>
    <ListGroup.Item>And a fifth one</ListGroup.Item>
</ListGroup.Root>
```

## Active Items

Add `isActive=true` to a `ListGroup.Item` to indicate the current active selection.

- Active item
- A second item
- A third item
- A fourth item
- And a fifth one

```html
<ListGroup.Root>
    <ListGroup.Item isActive={true}>Active item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
    <ListGroup.Item>A fourth item</ListGroup.Item>
    <ListGroup.Item>And a fifth one</ListGroup.Item>
</ListGroup.Root>
```

## Links and Buttons

Use `isActionable=true` to make list items clickable with hover effects. This is useful for creating interactive lists.

```html
<ListGroup.Root>
    <ListGroup.ItemAction href="#!" isActive={true}>The current link item</ListGroup.ItemAction>
    <ListGroup.ItemAction href="#!">A second link item</ListGroup.ItemAction>
    <ListGroup.ItemAction onclick={() => console.log('click')}>A button item</ListGroup.ItemAction>
    <ListGroup.ItemAction onclick={() => console.log('click')}>A second button item</ListGroup.ItemAction>
    <ListGroup.ItemAction href="#!" isDisabled={true}>A disabled link item</ListGroup.ItemAction>
    <ListGroup.ItemAction isDisabled={true}>A disabled button item</ListGroup.ItemAction>
</ListGroup.Root>
```

## Flush

Add `isFlush=true` to remove some borders and rounded corners to render list items edge-to-edge in a parent container (e.g., a card).

- An item
- A second item
- A third item
- A fourth item
- And a fifth one

```html
<ListGroup.Root isFlush={true}>
    <ListGroup.Item>An item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
    <ListGroup.Item>A fourth item</ListGroup.Item>
    <ListGroup.Item>And a fifth one</ListGroup.Item>
</ListGroup.Root>
```

## Numbered List

Add `isNumbered=true` to your `ListGroup.Root` to opt into numbered list group items. Numbers are generated via CSS.

1. First item
2. Second item
3. Third item
4. Fourth item
5. Fifth item

```html
<ListGroup.Root isNumbered={true}>
    <ListGroup.Item>First item</ListGroup.Item>
    <ListGroup.Item>Second item</ListGroup.Item>
    <ListGroup.Item>Third item</ListGroup.Item>
    <ListGroup.Item>Fourth item</ListGroup.Item>
    <ListGroup.Item>Fifth item</ListGroup.Item>
</ListGroup.Root>
```

## Horizontal

Add `horizontalOnBreakpoint` to change the layout of list group items from vertical to horizontal across all breakpoints.

- An item
- A second item
- A third item

- An item
- A second item
- A third item

- An item
- A second item
- A third item

- An item
- A second item
- A third item

- An item
- A second item
- A third item

- An item
- A second item
- A third item

```html
<ListGroup.Root horizontalOnBreakpoint="xs">
    <ListGroup.Item>An item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
</ListGroup.Root>
<ListGroup.Root horizontalOnBreakpoint="sm">
    <ListGroup.Item>An item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
</ListGroup.Root>
<ListGroup.Root horizontalOnBreakpoint="md">
    <ListGroup.Item>An item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
</ListGroup.Root>
<ListGroup.Root horizontalOnBreakpoint="lg">
    <ListGroup.Item>An item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
</ListGroup.Root>
<ListGroup.Root horizontalOnBreakpoint="xl">
    <ListGroup.Item>An item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
</ListGroup.Root>
<ListGroup.Root horizontalOnBreakpoint="xxl">
    <ListGroup.Item>An item</ListGroup.Item>
    <ListGroup.Item>A second item</ListGroup.Item>
    <ListGroup.Item>A third item</ListGroup.Item>
</ListGroup.Root>
```

## Contextual Colors

Use the `colorVariant` prop to style list items with a contextual color.

- Primary
- Secondary
- Success
- Danger
- Warning
- Info
- Light
- Dark

```html
<ListGroup.Root>
    <ListGroup.Item colorVariant="primary">Primary</ListGroup.Item>
    <ListGroup.Item colorVariant="secondary">Secondary</ListGroup.Item>
    <ListGroup.Item colorVariant="success">Success</ListGroup.Item>
    <ListGroup.Item colorVariant="danger">Danger</ListGroup.Item>
    <ListGroup.Item colorVariant="warning">Warning</ListGroup.Item>
    <ListGroup.Item colorVariant="info">Info</ListGroup.Item>
    <ListGroup.Item colorVariant="light">Light</ListGroup.Item>
    <ListGroup.Item colorVariant="dark">Dark</ListGroup.Item>
</ListGroup.Root>
```

## For links and buttons

Use the `colorVariant` prop to style anchors and buttons within the list group with a contextual color. Note the addition of the hover styles here not present in the previous example. Also supported is the .active state; apply it to indicate an active selection on a contextual list group item.

```html
<script>
    let currentContextualColor: ListGroupItemColorVariant | undefined = $state(undefined);
</script>
<ListGroup.Root>
    <ListGroup.ItemAction
        href="#!"
        colorVariant="primary"
        isActive={currentContextualColor === 'primary'}
        onclick={() => (currentContextualColor = 'primary')}>Primary</ListGroup.ItemAction>
    <ListGroup.ItemAction
        href="#!"
        colorVariant="secondary"
        isActive={currentContextualColor === 'secondary'}
        onclick={() => (currentContextualColor = 'secondary')}>Secondary</ListGroup.ItemAction>
    <ListGroup.ItemAction
        href="#!"
        colorVariant="success"
        isActive={currentContextualColor === 'success'}
        onclick={() => (currentContextualColor = 'success')}>Success</ListGroup.ItemAction>
    <ListGroup.ItemAction
        href="#!"
        colorVariant="danger"
        isActive={currentContextualColor === 'danger'}
        onclick={() => (currentContextualColor = 'danger')}>Danger</ListGroup.ItemAction>
    <ListGroup.ItemAction
        href="#!"
        colorVariant="warning"
        isActive={currentContextualColor === 'warning'}
        onclick={() => (currentContextualColor = 'warning')}>Warning</ListGroup.ItemAction>
    <ListGroup.ItemAction
        href="#!"
        colorVariant="info"
        isActive={currentContextualColor === 'info'}
        onclick={() => (currentContextualColor = 'info')}>Info</ListGroup.ItemAction>
    <ListGroup.ItemAction
        href="#!"
        colorVariant="light"
        isActive={currentContextualColor === 'light'}
        onclick={() => (currentContextualColor = 'light')}>Light</ListGroup.ItemAction>
    <ListGroup.ItemAction
        href="#!"
        colorVariant="dark"
        isActive={currentContextualColor === 'dark'}
        onclick={() => (currentContextualColor = 'dark')}>Dark</ListGroup.ItemAction>
</ListGroup.Root>
```

## With badges

Add badges to any list group item to show unread counts, activity, and more with the help of some utilities./p>

- A list item 14
- A second list item 2
- A third list item 1

```html
<ListGroup.Root>
    <ListGroup.Item class="d-flex justify-content-between align-items-center">
        A list item
        <Badge isPill={true}>14</Badge>
    </ListGroup.Item>
    <ListGroup.Item class="d-flex justify-content-between align-items-center">
        A second list item
        <Badge isPill={true}>2</Badge>
    </ListGroup.Item>
    <ListGroup.Item class="d-flex justify-content-between align-items-center">
        A third list item
        <Badge isPill={true}>1</Badge>
    </ListGroup.Item>
</ListGroup.Root>
```

## Custom Content

List groups can contain any content, including headings, paragraphs, and more.

```html
<ListGroup.Root>
    <ListGroup.ItemAction href="#!" isActive={true}>
        <div class="d-flex w-100 justify-content-between">
            <h5 class="mb-1">List group item heading</h5>
            <small>3 days ago</small>
        </div>
        <p class="mb-1">Some placeholder content in a paragraph.</p>
        <small>And some small print.</small>
    </ListGroup.ItemAction>
    <ListGroup.ItemAction href="#!">
        <div class="d-flex w-100 justify-content-between">
            <h5 class="mb-1">List group item heading</h5>
            <small class="text-body-secondary">3 days ago</small>
        </div>
        <p class="mb-1">Some placeholder content in a paragraph.</p>
        <small class="text-body-secondary">And some muted small print.</small>
    </ListGroup.ItemAction>
    <ListGroup.ItemAction href="#!">
        <div class="d-flex w-100 justify-content-between">
            <h5 class="mb-1">List group item heading</h5>
            <small class="text-body-secondary">3 days ago</small>
        </div>
        <p class="mb-1">Some placeholder content in a paragraph.</p>
        <small class="text-body-secondary">And some muted small print.</small>
    </ListGroup.ItemAction>
</ListGroup.Root>
```

## Checkboxes and Radios

Use checkboxes or radios within list group items to create selectable lists.

- Checkbox item
- Radio item

```html
<ListGroup.Root>
    <ListGroup.Item>
        <input type="checkbox" class="form-check-input me-1" />
        Checkbox item
    </ListGroup.Item>
    <ListGroup.Item>
        <input type="radio" name="options" class="form-check-input me-1" />
        Radio item
    </ListGroup.Item>
</ListGroup.Root>
```

## API Reference

### ListGroup.Root Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `id` | `string` | `list-group-{uid}` | Unique ID for the pagination item element. |
| `isFlush` | `boolean` | `false` | Removes borders and rounded corners to render list items edge-to-edge in a parent container |
| `horizontalOnBreakpoint` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl' \| undefined` | - | Changes the layout of list group items from vertical to horizontal at the specified breakpoint |
| `isNumbered` | `boolean` | `false` | Renders list items with numbers generated using the OL element |

### ListGroup.Item Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `id` | `string` | `list-group-item-{uid}` | Unique ID for the pagination item element. |
| `isActive` | `boolean` | `false` | Indicates the current active selection |
| `isDisabled` | `boolean` | `false` | Makes the item appear disabled |
| `colorVariant` | `'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning' \| 'info' \| 'light' \| 'dark' \| undefined` | - | Contextual color variant for the list item |

### ListGroup.ItemAction Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `colorVariant` | `'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning' \| 'info' \| 'light' \| 'dark' \| undefined` | - | Contextual color variant for the action item |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `href` | `string` | - | URL to navigate to when the item is clicked; renders the item as an anchor tag when provided |
| `id` | `string` | `list-group-item-action-{uid}` | Unique ID for the action item element |
| `isActive` | `boolean` | `false` | Indicates the current active selection |
| `isDisabled` | `boolean` | `false` | Makes the action item appear disabled |
| `onclick` | `EventListener` | `noop` | Click event handler for the action item |

### CSS Classes

The component applies Bootstrap's list-group classes based on the provided props:

- `list-group` - Applied to ListGroup.Root
- `list-group-item` - Applied to ListGroup.Item and ListGroup.ItemAction
- `list-group-flush` - Applied when isFlush=true
- `list-group-horizontal` - Applied when horizontalOnBreakpoint='xs'
- `list-group-horizontal-{breakpoint}` - Applied when horizontalOnBreakpoint is set (sm, md, lg, xl, xxl)
- `list-group-numbered` - Applied when isNumbered=true
- `list-group-item-{colorVariant}` - Applied when colorVariant prop is set (primary, secondary, etc.)
- `list-group-item-action` - Applied to ListGroup.ItemAction
- `active` - Applied to ListGroup.Item or ListGroup.ItemAction when isActive=true
- `disabled` - Applied to ListGroup.ItemAction when isDisabled=true