Powered by NeGD | MeitY Government of India® UX4G
List Group
List groups are a versatile and effective tool for showing a number of pieces of content. Developers can expand and modify them to support virtually any material within.
Basic example #
An unordered list with list items and the appropriate classes is the most fundamental list group. Add to it using the choices that are provided below or, if necessary, your own CSS.
<ul class="list-group"><li class="list-group-item">An item</li><li class="list-group-item">A second item</li><li class="list-group-item">A third item</li><li class="list-group-item">A fourth item</li><li class="list-group-item">And a fifth one</li></ul>
RESULT
- An item
- A second item
- A third item
- A fourth item
- And a fifth one
Active items #
Add .active
to a
.list-group-item
to indicate the current active
selection.
<ul class="list-group"><li class="list-group-item active" aria-current="true">An active item</li><li class="list-group-item">A second item</li><li class="list-group-item">A third item</li><li class="list-group-item">A fourth item</li><li class="list-group-item">And a fifth one</li></ul>
RESULT
- An active item
- A second item
- A third item
- A fourth item
- And a fifth one
Disabled items #
An unordered list with list items and the appropriate classes is the most fundamental list group. Add to it using the choices that are provided below or, if necessary, your own CSS.
<ul class="list-group"><li class="list-group-item disabled" aria-disabled="true">A disabled item</li><li class="list-group-item">A second item</li><li class="list-group-item">A third item</li><li class="list-group-item">A fourth item</li><li class="list-group-item">And a fifth one</li></ul>
RESULT
- A disabled item
- A second item
- A third item
- A fourth item
- And a fifth one
Links & buttons #
By adding .list-group-item-action, you may use <a>
s or button>s to create actionable list group items with hover, disabled, and active states. To make sure list groups comprised of non-interactive components (such <li>
s or <div>
s) don't offer a click or tap affordance, we segregate these pseudo-classes.
Be sure to not use the
standard .btn
classes
here.
<div class="list-group"><a href="#" class="list-group-item list-group-item-action active" aria-current="true">The current link item</a><a href="#" class="list-group-item list-group-item-action">A second link item</a><a href="#" class="list-group-item list-group-item-action">A third link item</a><a href="#" class="list-group-item list-group-item-action">A fourth link item</a><a class="list-group-item list-group-item-action disabled">A disabled link item</a></div>
RESULT
With <button>
s, you can
also make use of the disabled
attribute instead of
the .disabled
class. Sadly, <a>
s
don’t support the disabled attribute.
<div class="list-group"><button type="button" class="list-group-item list-group-item-action active" aria-current="true">The current button</button><button type="button" class="list-group-item list-group-item-action">A second button item</button><button type="button" class="list-group-item list-group-item-action">A third button item</button><button type="button" class="list-group-item list-group-item-action">A fourth button item</button><button type="button" class="list-group-item list-group-item-action" disabled>A disabled button item</button></div>
RESULT
Flush #
To render list group elements edge-to-edge in a parent container (such as cards), add .list-group-flush
to remove some borders and rounded corners.
<ul class="list-group list-group-flush"><li class="list-group-item">An item</li><li class="list-group-item">A second item</li><li class="list-group-item">A third item</li><li class="list-group-item">A fourth item</li><li class="list-group-item">And a fifth one</li></ul>
RESULT
- An item
- A second item
- A third item
- A fourth item
- And a fifth one
Numbered #
To opt into numbered list group items, add the .list-group-numbered
modifier class (and omit the <ol>
element, if desired). To enable more customisation and better placement inside list group items, numbers are generated using CSS (as opposed to an <ol>
s default browser styling).
Counter-reset
on the <ol>
is used to create numbers, which are then stylized and placed on the <li>
with counter-increment and content using ::before pseudo-element
.
<ol class="list-group list-group-numbered"><li class="list-group-item">A list item</li><li class="list-group-item">A list item</li><li class="list-group-item">A list item</li></ol>
RESULT
- A list item
- A list item
- A list item
These work great with custom content as well.
<ol class="list-group list-group-numbered"><li class="list-group-item d-flex justify-content-between align-items-start"><div class="ms-2 me-auto"><div class="fw-bold">Subheading</div>Content for list item</div><span class="badge bg-primary rounded-pill">14</span></li><li class="list-group-item d-flex justify-content-between align-items-start"><div class="ms-2 me-auto"><div class="fw-bold">Subheading</div>Content for list item</div><span class="badge bg-primary rounded-pill">14</span></li><li class="list-group-item d-flex justify-content-between align-items-start"><div class="ms-2 me-auto"><div class="fw-bold">Subheading</div>Content for list item</div><span class="badge bg-primary rounded-pill">14</span></li></ol>
RESULT
-
SubheadingContent for list item
-
SubheadingContent for list item
-
SubheadingContent for list item
Horizontal #
To alter the list group item layout from vertical to horizontal across all breakpoints, add .list-group-horizontal
. Select a responsive variation instead to create a list group horizontal beginning at that breakpoint's min-width, use the command .list-group-horizontal-{sm|md|lg|xl|xxl}
. At the moment, flush list groups and horizontal list groups cannot be mixed.
ProTip: Do you like equal-width list groups for horizontal
lists? Each list group item should have .flex-fill
.
<ul class="list-group list-group-horizontal">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-sm">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-md">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-lg">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-xl">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-xxl">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
RESULT
- 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
Contextual classes #
Also compatible with .list-group-item-action
are contextual classes. Notice how the hover styles have been included here, which were not present in the prior example. The .active
state is also supported; use it to show that a contextual list group item has an active selection.
<ul class="list-group"><li class="list-group-item">A simple default list group item</li><li class="list-group-item list-group-item-primary">A simple primary list group item</li><li class="list-group-item list-group-item-secondary">A simple secondary list group item</li><li class="list-group-item list-group-item-success">A simple success list group item</li><li class="list-group-item list-group-item-danger">A simple danger list group item</li><li class="list-group-item list-group-item-warning">A simple warning list group item</li><li class="list-group-item list-group-item-info">A simple info list group item</li><li class="list-group-item list-group-item-light">A simple light list group item</li><li class="list-group-item list-group-item-dark">A simple dark list group item</li></ul>
RESULT
- A simple default list group item
- A simple primary list group item
- A simple secondary list group item
- A simple success list group item
- A simple danger list group item
- A simple warning list group item
- A simple info list group item
- A simple light list group item
- A simple dark list group item
Contextual classes also work with
.list-group-item-action
. 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.
<div class="list-group"><a href="#" class="list-group-item list-group-item-action">A simple default list group item</a><a href="#" class="list-group-item list-group-item-action list-group-item-primary">A simple primary list group item</a><a href="#" class="list-group-item list-group-item-action list-group-item-secondary">A simple secondary list group item</a><a href="#" class="list-group-item list-group-item-action list-group-item-success">A simple success list group item</a><a href="#" class="list-group-item list-group-item-action list-group-item-danger">A simple danger list group item</a><a href="#" class="list-group-item list-group-item-action list-group-item-warning">A simple warning list group item</a><a href="#" class="list-group-item list-group-item-action list-group-item-info">A simple info list group item</a><a href="#" class="list-group-item list-group-item-action list-group-item-light">A simple light list group item</a><a href="#" class="list-group-item list-group-item-action list-group-item-dark">A simple dark list group item</a></div>
RESULT
Conveying meaning to assistive technologies
Color-coding
to add meaning just gives a visual cue, which users of assistive technologies like screen readers won't be able to understand. Make sure the information the color designates is either evident from the content itself (such as the visible text) or is included in another way, such as by hiding additional text using the .visually-hidden
class.
With badges #
Add badges to any list group item to show unread counts, activity, and more with the help of some utilities.
<ul class="list-group"><li class="list-group-item d-flex justify-content-between align-items-center">A list item<span class="badge bg-primary rounded-pill">14</span></li><li class="list-group-item d-flex justify-content-between align-items-center">A second list item<span class="badge bg-primary rounded-pill">2</span></li><li class="list-group-item d-flex justify-content-between align-items-center">A third list item<span class="badge bg-primary rounded-pill">1</span></li></ul>
RESULT
- A list item 14
- A second list item 2
- A third list item 1
Custom content #
Add nearly any HTML within, even for linked list groups like the one below, with the help of flexbox utilities.
<div class="list-group"><a href="#" class="list-group-item list-group-item-action active" aria-current="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></a><a href="#" class="list-group-item list-group-item-action"><div class="d-flex w-100 justify-content-between"><h5 class="mb-1">List group item heading</h5><small class="text-muted">3 days ago</small></div><p class="mb-1">Some placeholder content in a paragraph.</p><small class="text-muted">And some muted small print.</small></a><a href="#" class="list-group-item list-group-item-action"><div class="d-flex w-100 justify-content-between"><h5 class="mb-1">List group item heading</h5><small class="text-muted">3 days ago</small></div><p class="mb-1">Some placeholder content in a paragraph.</p><small class="text-muted">And some muted small print.</small></a></div>
RESULT
List group item heading
3 days agoSome placeholder content in a paragraph.
And some small print.List group item heading
3 days agoSome placeholder content in a paragraph.
And some muted small print.List group item heading
3 days agoSome placeholder content in a paragraph.
And some muted small print.Checkboxes and radios #
Put the checkboxes
and radios from UX4G into list group elements, then edit as necessary. If you want to make them accessible, you can use them without
<ul class="list-group"><li class="list-group-item"><input class="form-check-input me-1" type="checkbox" value="" id="firstCheckbox"/><label class="form-check-label" for="firstCheckbox">First checkbox</label></li><li class="list-group-item"><input class="form-check-input me-1" type="checkbox" value="" id="secondCheckbox"/><label class="form-check-label" for="secondCheckbox">Second checkbox</label></li><li class="list-group-item"><input class="form-check-input me-1" type="checkbox" value="" id="thirdCheckbox"/><label class="form-check-label" for="thirdCheckbox">Third checkbox</label></li></ul>
RESULT
<ul class="list-group"><li class="list-group-item"><input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="firstRadio" checked/><label class="form-check-label" for="firstRadio">First radio</label></li><li class="list-group-item"><input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="secondRadio"/><label class="form-check-label" for="secondRadio">Second radio</label></li><li class="list-group-item"><input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="thirdRadio"/><label class="form-check-label" for="thirdRadio">Third radio</label></li></ul>
RESULT
You can use .stretched-link
on
<label>
s to make the whole list group item
clickable.
<ul class="list-group"><li class="list-group-item"><input class="form-check-input me-1" type="checkbox" value="" id="firstCheckboxStretched"/><label class="form-check-label stretched-link" for="firstCheckboxStretched">First checkbox</label></li><li class="list-group-item"><input class="form-check-input me-1" type="checkbox" value="" id="secondCheckboxStretched"/><label class="form-check-label stretched-link" for="secondCheckboxStretched">Second checkbox</label></li><li class="list-group-item"><input class="form-check-input me-1" type="checkbox" value="" id="thirdCheckboxStretched"/><label class="form-check-label stretched-link" for="thirdCheckboxStretched">Third checkbox</label></li></ul>
RESULT
CSS #
Variables #
Added in v1.0.0
List groups now employ local CSS variables
on .list-group for improved real-time customisation as part of UX4G's growing CSS variables
strategy. Sass is used to set the values for the CSS variables, therefore Sass customization is still available.
--#{$prefix}list-group-color: #{$list-group-color};
--#{$prefix}list-group-bg: #{$list-group-bg};
--#{$prefix}list-group-border-color: #{$list-group-border-color};
--#{$prefix}list-group-border-width: #{$list-group-border-width};
--#{$prefix}list-group-border-radius: #{$list-group-border-radius};
--#{$prefix}list-group-item-padding-x: #{$list-group-item-padding-x};
--#{$prefix}list-group-item-padding-y: #{$list-group-item-padding-y};
--#{$prefix}list-group-action-color: #{$list-group-action-color};
--#{$prefix}list-group-action-hover-color: #{$list-group-action-hover-color};
--#{$prefix}list-group-action-hover-bg: #{$list-group-hover-bg};
--#{$prefix}list-group-action-active-color: #{$list-group-action-active-color};
--#{$prefix}list-group-action-active-bg: #{$list-group-action-active-bg};
--#{$prefix}list-group-disabled-color: #{$list-group-disabled-color};
--#{$prefix}list-group-disabled-bg: #{$list-group-disabled-bg};
--#{$prefix}list-group-active-color: #{$list-group-active-color};
--#{$prefix}list-group-active-bg: #{$list-group-active-bg};
--#{$prefix}list-group-active-border-color: #{$list-group-active-border-color};
Sass variables #
$list-group-color: $gray-900;
$list-group-bg: $white;
$list-group-border-color: rgba($black, .125);
$list-group-border-width: $border-width;
$list-group-border-radius: $border-radius;
$list-group-item-padding-y: $spacer * .5;
$list-group-item-padding-x: $spacer;
$list-group-item-bg-scale: -80%;
$list-group-item-color-scale: 40%;
$list-group-hover-bg: $gray-100;
$list-group-active-color: $component-active-color;
$list-group-active-bg: $component-active-bg;
$list-group-active-border-color: $list-group-active-bg;
$list-group-disabled-color: $gray-600;
$list-group-disabled-bg: $list-group-bg;
$list-group-action-color: $gray-700;
$list-group-action-hover-color: $list-group-action-color;
$list-group-action-active-color: $body-color;
$list-group-action-active-bg: $gray-200;
Mixins #
Used in combination with
$theme-colors
to generate the contextual variant classes for
.list-group-items
.
Loop #
Loop that generates the modifier classes
with the list-group-item-variant()
mixin.
// List group contextual variants
//
// Add modifier classes to change text and background color on individual items.
// Organizationally, this must come after the `:hover` states.
@each $state, $value in $theme-colors {
$list-group-variant-bg: shift-color($value, $list-group-item-bg-scale);
$list-group-variant-color: shift-color($value, $list-group-item-color-scale);
@if (contrast-ratio($list-group-variant-bg, $list-group-variant-color) < $min-contrast-ratio) {
$list-group-variant-color: mix($value, color-contrast($list-group-variant-bg), abs($list-group-item-color-scale));
}
@include list-group-item-variant($state, $list-group-variant-bg, $list-group-variant-color);
}
JavaScript behavior #
Use the tab JavaScript plugin—include
it individually or through the compiled UX4G.js
file—to extend our list group to create tabbable panes of local
content.
<div class="row"><div class="col-4"><div class="list-group" id="list-tab" role="tablist"><a class="list-group-item list-group-item-action active" id="list-home-list" data-bs-toggle="list" href="#list-home" role="tab" aria-controls="list-home">Home</a><a class="list-group-item list-group-item-action" id="list-profile-list" data-bs-toggle="list" href="#list-profile" role="tab" aria-controls="list-profile">Profile</a><a class="list-group-item list-group-item-action" id="list-messages-list" data-bs-toggle="list" href="#list-messages" role="tab" aria-controls="list-messages">Messages</a><a class="list-group-item list-group-item-action" id="list-settings-list" data-bs-toggle="list" href="#list-settings" role="tab" aria-controls="list-settings">Settings</a></div></div><div class="col-8"><div class="tab-content" id="nav-tabContent"><div class="tab-pane fade show active" id="list-home" role="tabpanel" aria-labelledby="list-home-list">...</div><div class="tab-pane fade" id="list-profile" role="tabpanel" aria-labelledby="list-profile-list">...</div><div class="tab-pane fade" id="list-messages" role="tabpanel" aria-labelledby="list-messages-list">...</div><div class="tab-pane fade" id="list-settings" role="tabpanel" aria-labelledby="list-settings-list">...</div></div></div></div>
RESULT
Some placeholder content in a paragraph relating to "Home". And some more content, used here just to pad out and fill this tab panel. In production, you would obviously have more real content here. And not just text. It could be anything, really. Text, images, forms.
Some placeholder content in a paragraph relating to "Profile". And some more content, used here just to pad out and fill this tab panel. In production, you would obviously have more real content here. And not just text. It could be anything, really. Text, images, forms.
Some placeholder content in a paragraph relating to "Messages". And some more content, used here just to pad out and fill this tab panel. In production, you would obviously have more real content here. And not just text. It could be anything, really. Text, images, forms.
Some placeholder content in a paragraph relating to "Settings". And some more content, used here just to pad out and fill this tab panel. In production, you would obviously have more real content here. And not just text. It could be anything, really. Text, images, forms.
Using data attributes #
By just putting data-bs-toggle="list"
or on an element, you can activate a list group navigation without coding any JavaScript. Use the .list-group-item
data attributes.
<div role="tabpanel">
<!-- List group -->
<div class="list-group" id="myList" role="tablist">
<a class="list-group-item list-group-item-action active" data-bs-toggle="list" href="#home" role="tab">Home</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#profile" role="tab">Profile</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#messages" role="tab">Messages</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#settings" role="tab">Settings</a>
</div>
<!-- Tab panes -->
<div class="tab-content">
<div class="tab-pane active" id="home" role="tabpanel">...</div>
<div class="tab-pane" id="profile" role="tabpanel">...</div>
<div class="tab-pane" id="messages" role="tabpanel">...</div>
<div class="tab-pane" id="settings" role="tabpanel">...</div>
</div>
</div>
Via JavaScript #
Enable tabbable list item via JavaScript (each list item needs to be activated individually):
const triggerTabList = document.querySelectorAll('#myTab a')
triggerTabList.forEach(triggerEl => {
const tabTrigger = new bootstrap.Tab(triggerEl)
triggerEl.addEventListener('click', event => {
event.preventDefault()
tabTrigger.show()
})
})
You can activate individual list item in several ways:
const triggerEl = document.querySelector('#myTab a[href="#profile"]')
bootstrap.Tab.getInstance(triggerEl).show() // Select tab by name
const triggerFirstTabEl = document.querySelector('#myTab li:first-child a')
bootstrap.Tab.getInstance(triggerFirstTabEl).show() // Select first tab
Fade effect #
Add .fade
to each .tab-pane
to have the tabs panel fade in. For the original content to be displayed, the first tab pane also has to have show.
<div class="tab-content">
<div class="tab-pane fade show active" id="home" role="tabpanel">...</div>
<div class="tab-pane fade" id="profile" role="tabpanel">...</div>
<div class="tab-pane fade" id="messages" role="tabpanel">...</div>
<div class="tab-pane fade" id="settings" role="tabpanel">...</div>
</div>
Methods #
constructor #
Activates a content container and list item element. Either a data-bs-target
or a href targeting a container node in the DOM should be present in a tab.
<div class="list-group" id="myList" role="tablist"> <a class="list-group-item list-group-item-action active" data-bs-toggle="list" href="#home" role="tab">Home</a> <a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#profile" role="tab">Profile</a> <a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#messages" role="tab">Messages</a> <a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#settings" role="tab">Settings</a></div><div class="tab-content"> <div class="tab-pane active" id="home" role="tabpanel">...</div> <div class="tab-pane" id="profile" role="tabpanel">...</div> <div class="tab-pane" id="messages" role="tabpanel">...</div> <div class="tab-pane" id="settings" role="tabpanel">...</div></div><script> const firstTabEl = document.querySelector('#myTab a:last-child') const firstTab = new UX4G.Tab(firstTabEl) firstTab.show()</script>
Show #
Selects the given list item and shows its associated pane. Any previously selected list item that was also associated with a hidden window becomes unselected. returns to the caller before the tab pane has actually been displayed (for example, prior to the occurrence of the shown.bs.tab event).
const tab = new UX4G.Tab('#someListItem')
tab.show()
dispose #
Destroys an element’s tab.
getInstance #
Static method which allows you to get the tab instance associated with a DOM element
const tab = UX4G.Tab.getInstance('#trigger') // Returns a UX4G tab instance
getOrCreateInstance #
Static method which allows you to get the tab instance associated with a DOM element, or create a new one in case it wasn’t initialized
const tab = bootstrap.Tab.getOrCreateInstance('#trigger') // Returns a UX4G tab instance
Events #
When showing a new tab, the events fire in the following order:
hide.bs.tab
(on the current active tab)show.bs.tab
(on the to-be-shown tab)hidden.bs.tab
(on the previous active tab, the same one as for thehide.bs.tab
event)shown.bs.tab
(on the newly-active just-shown tab, the same one as for theshow.bs.tab
event)
If no tab was already active, the
hide.bs.tab
and hidden.bs.tab
events
will not be fired.
Event type | Description |
---|---|
hide.bs.tab |
This event fires when a new tab is to be shown
(and thus the previous active tab is to be
hidden). Use event.target and
event.relatedTarget to target the
current active tab and the new soon-to-be-active
tab, respectively.
|
hidden.bs.tab |
This event fires after a new tab is shown (and
thus the previous active tab is hidden). Use
event.target and
event.relatedTarget to target the
previous active tab and the new active tab,
respectively.
|
show.bs.tab |
This event fires on tab show, but before the new
tab has been shown. Use
event.target and
event.relatedTarget to target the
active tab and the previous active tab (if
available) respectively.
|
shown.bs.tab |
This event fires on tab show after a tab has
been shown. Use event.target and
event.relatedTarget to target the
active tab and the previous active tab (if
available) respectively.
|
const tabElms = document.querySelectorAll('a[data-bs-toggle="list"]')
tabElms.forEach(tabElm => {
tabElm.addEventListener('shown.bs.tab', event => {
event.target // newly activated tab
event.relatedTarget // previous active tab
})
})