Lists
Lists allow for multiple ways to visually organize a series of content or navigation.
Contents
Overview
Lists are a flexible component for displaying a series of content with various styling options. List items can be modified and extended to support just about any content within. They can also be used as navigation with the right modifier class.
Basic List
In the basic form, a .list
removes the default list-style
and left margin on list items, but nested lists will be indented.
The use of the .list-item
class required for each <li>
or simulated list item, for proper styling.
- List item 1
- List item 2
- List item 3
You can also use <div>
containers to create a list.
Styled Lists
Add some visual style to lists with a handful of modifier classes.
Bulleted List
Add the .list-bulleted
modifier to add a stylized bullet to each list item.
- Bulleted list item 1
- Bulleted list item 2
- Bulleted list item 3
Ordered List
Add the .list-ordered
modifier to create a numerically ordered list.
- Ordered list item 1
- Ordered list item 2
- Ordered list item 3
Nested Lists
When nesting lists, you will need to add the .list
class and any modifiers to each nested list to restyle as needed.
- List item 1
- List item 2
- List item 1
- List item 2
- List item 3
- List item 3
- Bulleted list item 1
- Bulleted list item 2
- Bulleted list item 1
- Bulleted list item 2
- Bulleted list item 3
- List item 3
- Ordered list item 1
- Ordered list item 2
- Ordered list item 1
- Ordered list item 2
- Ordered list item 3
- List item 3
- List item 1
- List item 2
- Bulleted list item 1
- Bulleted list item 2
- Bulleted list item 3
- List item 3
- List item 1
- List item 2
- Ordered list item 1
- Ordered list item 2
- Ordered list item 3
- List item 3
- Bulleted list item 1
- Bulleted list item 2
- Ordered list item 1
- Ordered list item 2
- Ordered list item 3
- Bulleted list item 3
- Ordered list item 1
- Ordered list item 2
- Bulleted list item 1
- Bulleted list item 2
- Bulleted list item 3
- Ordered list item 3
Divided List
Place a rule between list items with the .list-divided
modifier.
- Divided list item 1
- Divided list item 2
- Divided list item 3
Divided lists also work with <div>
containers.
Ruled List
Place a rule at the top and bottom of a list, and between list items with the .list-ruled
modifier.
- Ruled list item 1
- Ruled list item 2
- Ruled list item 3
Similar to divided lists, ruled lists also work with <div>
containers.
List Group
Visually group list content by adding a border all around with the .list-group
modifier.
- List item
- List item
- List item
Similar to the above examples, this will also work with <div>
containers.
Spaced
Easily add some spacing to lists. Adding .list-spaced
will provide padding on all sides of each list item.
Add only vertical padding with .list-spaced-y
.
Need only horizontal padding, then use .list-spaced-x
.
Horizontal Lists
Place the items in the list in a horizontal layout with .list-horizontal
.
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
- List item
Inline List
Add the .flex-wrap
utility class onto a horizontal list to wrap to the next row as needed.
- Inline list item
- Inline list item
- Inline list item
- Inline list item
- Inline list item
- Inline list item
- Inline list item
- Inline list item
- Inline list item
- Inline list item
List Content
Active Items
Add .active
to a .list-item
to indicate the current active selection.
- Active list item
- List item 2
- List item 3
Disabled Items
Add .disabled
to a <li>
or .list-item
to make it out to appear disabled. Note that some elements with .disabled
will also require custom JavaScript to fully disable their click events (e.g., links).
Disabling Anchors
Please refer to the Accessiblity notes about disabled anchors.
- Disabled list item
- List item 2
- List item 3
Links and Buttons
Use <a>
s or <button>
s to create actionable list items with hover, disabled, and active states by adding .list-item-action
. We separate these pseudo-classes to ensure lists made of non-interactive elements (like <li>
s or <div>
s) don’t provide a click or tap affordance.
Be sure to not use the standard .btn
classes here.
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.
Adding Badges
Add badges to any list item to show unread counts, activity, and more with the help of some flexbox utility classes.
- Cras justo odio 7
- Dapibus ac facilisis in 12
- Morbi leo risus 3
Custom Content
Add nearly any HTML within, even for linked lists like the one below, using flexbox utilities for layout.
List item heading
3 days agoDonec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.
Donec id elit non mi porta.List item heading
3 days agoDonec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.
Donec id elit non mi porta.List item heading
3 days agoDonec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.
Donec id elit non mi porta.Color Variants
Use color utility classes to style lists with color.
Conveying Meaning to Assistive Technologies
Please refer to the Accessiblity notes about conveying meaning with color.
Rule Color
Divided and Ruled list items are defined with border-{side}-color: inherit;
, allowing for easy recoloring of the borders by setting the border-color
on the .list
itself. Setting a border-color
on a .list-item
will only update the border color for that specific list item.
- List item
- List item
- List item
Inverse List
Set a background color on a list. In some cases you may want to use additional color utility classes to adjust text or border color.
- List item
- List item
- List item
Contextual Classes
Use contextual classes to style list items with a stateful background and color.
- Default list item
- Primary list item
- Secondary list item
- Success list item
- Inof list item
- Warning list item
- Danger list item
- Light list item
- Dark list item
Contextual classes also work with .list-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 item. This is available with or without the use of .list-item-action
.
- Default list item
- Primary list item
- Success list item
- Info list item
- Warning list item
- Danger list item
- Light list item
- Dark list item
SASS Reference
Variables
The available Customization options, or Sass variables, that can be customized for list component.
Name | Type | Default | Description |
---|---|---|---|
$enable-list |
boolean | true |
Enable the generation of the list component classes.
Smaller segements of the list component classes can be disabled with the following $enable-* variables.
|
$enable-list-bulleted |
boolean | true |
Enable the generation of styled bulleted lists. |
$enable-list-ordered |
boolean | true |
Enable the generation of styled ordered lists. |
$enable-list-divided |
boolean | true |
Enable the generation of styled divided lists. |
$enable-list-ruled |
boolean | true |
Enable the generation of styled ruled lists. |
$enable-list-group |
boolean | true |
Enable the generation of list groups. |
$enable-list-spaced |
boolean | true |
Enable the generation of spaced lists. |
$enable-list-spaced-y |
boolean | true |
Enable the generation of vertically spaced lists. |
$enable-list-spaced-x |
boolean | true |
Enable the generation of horizontally spaced lists. |
$enable-list-horizontal |
boolean | true |
Enable the generation of styled horizontal lists. |
$enable-list-item-action |
boolean | true |
Enable the generation of list item actions. |
$enable-list-item-colors |
boolean | true |
Enable the generation of list item color variants. |
$list-margin-left |
string | 1.25rem |
Width of margin to indent lists. |
$list-margin-bottom |
string | 1rem |
Spacing below lists. |
$list-item-bg |
string | transparent |
Background color for list items. |
$list-item-disabled-bg |
string | $list-item-bg |
Background color for disabled list items. |
$list-item-disabled-color |
string | $component-disabled-color |
Text color for disabled list items. |
$list-item-active-bg |
string | $component-active-bg |
Background color for active list items. |
$list-item-active-color |
string | $component-active-color |
Text color for active list items. |
$list-item-active-border |
string | $component-active-border-color |
Border color for active list items. |
$list-item-action-color |
string | $component-action-color |
Text color for list item actions. |
$list-item-hover-color |
string | $list-item-hover-color |
Text color for list item actions when hovered or focused. |
$list-item-hover-bg |
string | $component-hover-bg |
Background color for list item actions when hovered or focused. |
$list-border-width |
string | $border-width |
Border width for list items with borders. |
$list-border-color |
string | $component-border-color |
Border color for list items with borders. |
$list-group-border-radius |
string | $border-radius |
Border radisu for list groups. |
$list-bulleted-content |
string | "\25cf\00a0" |
Visual content to use for bullets. Default content is a black circle and a space. |
$list-ordered-delimeter |
string | "\25cf\00a0" |
Visual content to use as a delimeter after the order value. Default content is a space. |
$list-horizontal-padding |
string | .5em |
Horizontal padding to use between list items in a horizontal list. |
$list-spaced-item-padding-y |
string | .75em |
Vertical padding for list items in a spaced list. |
$list-spaced-item-padding-x |
string | 1em |
Horizontal padding for list items in a spaced list. |
$list-themes |
map | () |
Map of color schemes for lists. |
$list-colors |
list | $base-colors |
Colors to mix and merge into $list-themes
|
$list-levels |
map | $level-context |
Levels to mix list colors with. |
Mixins
Here are the mixins related to lists that we use to help generate our CSS. You can also uses these mixins to generate your own custom components or utilities.
list-unstyled
List with no left padding or list item markers.
list-item-variant
Create a contextual color variant for a list item.
Argument | Type | Default | Description |
---|---|---|---|
$state |
string | '' |
The value appended to generate the class .list-item-#{$state} .
|
$bg |
string | none | Background color for a list item. |
$color |
string | none | Text color for a list item. |
$border |
string | none | Border color for a list item. |
$hover-bg |
string | none | Background color for a list item in active, hover, and focus states. |
$hover-color |
string | none | Text color for a list item in active, hover, and focus states.. |
$hover-border |
string | none | Border color for a list item in active, hover, and focus states.. |