Day 12: Bootstrap 4 Lists Tutorial and Examples

Hello and welcome to the 12th day of Bootstrap 4 πŸ˜‰ Today we will learn about Bootstrap 4 lists and Bootstrap 4 list groups. Besides offering multiple styles for the default list, Bootstrap 4 is introducing a new element: the list group. The Bootstrap 4 list group offers extensive use cases and learning how to add them to your project will help you organise your information and navigation.

Let’s start creating lists!

bootstrap-4-lists-start

Photo credit to Janice for her shot.

The article is organised into the following parts:

Bootstrap 4 Lists

Like we have mentioned in the Day 1: Bootstrap 4 CDN and Starter Template, Bootstrap 4 adds minor changes to the default styling for lists. You don’t need to add any new classes. Here is how basic lists (ordered and unordered) look in Bootstrap 4:

<ul>
  <li>The Great Gatsby</li>
  <li>The Grapes of Wrath</li>
  <li>Ulysses</li>
</ul>

<ol>
  <li>To Kill a Mockingbird</li>
  <li>1984</li>
  <li>Pride and Prejudice</li>
</ol>

Side note: I will be using lists of books in the examples. You can never get too many recommendations πŸ™‚

Unstyled List

Bootstrap 4 offers the possibility to create lists that don’t have the default list-style or a right margin. To get this simple look you need the .list-unstyled class. The class will only affect the immediate children in the list, so if you have nested lists, you will need to add the .list-unstyled class to the lists inside the list also.

<ul class="list-unstyled">
  <li>The Catcher in the Rye</li>
  <li>The Sound and the Fury</li>
  <li>Harry Potter Series
    <ul>
      <li>Harry Potter and the Sorcerer's Stone</li>
      <li>Harry Potter and the Chamber of Secrets</li>
      <li>Harry Potter and the Prisoner of Azkaban</li>
    </ul>
  </li>
</ul>

Inline List

If you want all the elements of the list to appear on the same line, horizontally, you need to add the .list-inline class to the <ul> tag and the .list-inline-item class to each <li> item.

<ul class="list-inline">
  <li class="list-inline-item">The Diary of a Young Girl</li>
  <li class="list-inline-item">The Little Prince</li>
  <li class="list-inline-item">Lord of the Flies</li>
</ul>

Description List

You can create lists that have two parts: on each line you can have a term and a definition. To align these two items horizontally you can use the grid system that we learned about in Bootstrap 4 grid tutorial. If you want to cut a longer piece of text, you can use the .text-truncated utility.

<dl class="row">
  <dt class="col-sm-3">Romeo and Juliet</dt>
  <dd class="col-sm-9">...</dd>

  <dt class="col-sm-3">Charlotte's Web </dt>
  <dd class="col-sm-9">
    <p>...</p>
    <p>...</p>
  </dd>

  <dt class="col-sm-3 text-truncate">Alice's Adventures in Wonderland & Through the Looking-Glass </dt>
  <dd class="col-sm-9">...</dd>
</dl>

Bootstrap 4 List Groups

Basic Example

List groups are unordered lists of items that have a special look: padding on each item and borders. To use them, you will need to add the .list-group class on the <ul> tag and .list-group-item on each <li> tag. Here is an example:

<ul class="list-group">
  <li class="list-group-item">The Lord of the Rings</li>
  <li class="list-group-item">One Hundred Years of Solitude</li>
  <li class="list-group-item">Brave New World</li>
  <li class="list-group-item">Gone with the Wind</li>
</ul>

If you want to remove the outside borders and have the corners right-angled, you can add the .list-group-flush class to the list. This will only keep the top borders top for the list items.

<ul class="list-group list-group-flush">
  <li class="list-group-item">The Lord of the Rings</li>
  <li class="list-group-item">One Hundred Years of Solitude</li>
  <li class="list-group-item">Brave New World</li>
  <li class="list-group-item">Gone with the Wind</li>
</ul>

Active Items

To show which element of the list is currently active, you can add the .active class (along with the .list-group-item class). This is how it looks:

<ul class="list-group">
  <li class="list-group-item">On the Road</li>
  <li class="list-group-item active">Pride and Prejudice</li>
  <li class="list-group-item">Anna Karenina</li>
</ul>

Disabled Items

And to disabled a list item, you can use the .disabled class on the .list-group-item element. Its content will be greyed out and will look like this:

<ul class="list-group">
  <li class="list-group-item">Animal Farm</li>
  <li class="list-group-item disabled">In Search of Lost Time <small>(out of stock)</small></li>
  <li class="list-group-item">Wuthering Heights</li>
</ul>

If you want to make the elements of the .list-group actionable you have two options. You can use anchors <a> instead of <li> and add the .list-group-item-action class for proper styling. Or you can use <button>s with the same .list-group-item-action class. By using buttons, you can use the disabled attribute. For <a> you need to use the .disabled class since <a> doesn’t support the disabled attribute.

//with links
<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action active">
    Hamlet
  </a>
  <a href="#" class="list-group-item list-group-item-action">Mody Dick</a>
  <a href="#" class="list-group-item list-group-item-action">The Color Purple</a>
  <a href="#" class="list-group-item list-group-item-action disabled">Midnight's Children</a>
</div>

//with buttons
<div class="list-group">
  <button type="button" class="list-group-item list-group-item-action active">
      Winnie-the-Pooh
    </button>
    <button type="button" class="list-group-item list-group-item-action">Slaughterhouse-Five</button>
    <button type="button" class="list-group-item list-group-item-action">War and Peace</button>
    <button type="button" class="list-group-item list-group-item-action" disabled>Of Mice and Men</button>
</div>

Colouring the List

To colour the background of list items, you can use the list contextual background classes for colour. These are different from the default background colouring classes .bg-[context] and have the format .list-group-item-[context]. Context can be one of the following: light, secondary, dark, primary, info, success, warning, danger.

<ul class="list-group">
  <li class="list-group-item">Little Women</li>
  <li class="list-group-item list-group-item-light">Native Son</li>
  <li class="list-group-item list-group-item-secondary">Great Expectations</li>
  <li class="list-group-item list-group-item-dark">The Sun Also Rises</li>
  <li class="list-group-item list-group-item-primary">The Stranger</li>
  <li class="list-group-item list-group-item-info">For Whom the Bell Tolls</li>
  <li class="list-group-item list-group-item-success">The Hobbit</li>
  <li class="list-group-item list-group-item-warning">Madame Bovary</li>
  <li class="list-group-item list-group-item-danger">The Wind in the Willows</li>
</ul>

If your list contains links or buttons, using .list-group-item-[context] classes will also provide styling for hover states.

<ul class="list-group">
  <a href="#" class="list-group-item list-group-item-action">Little Women</a>
  <a href="#" class="list-group-item list-group-item-action list-group-item-light">Native Son</a>
  <a href="#" class="list-group-item list-group-item-action list-group-item-secondary">Great Expectations</a>
  <a href="#" class="list-group-item list-group-item-action list-group-item-dark">The Sun Also Rises</a>
  <a href="#" class="list-group-item list-group-item-action list-group-item-primary">The Stranger</a>
  <a href="#" class="list-group-item list-group-item-action list-group-item-info">For Whom the Bell Tolls</a>
  <a href="#" class="list-group-item list-group-item-action list-group-item-success">The Hobbit</a>
  <a href="#" class="list-group-item list-group-item-action list-group-item-warning">Madame Bovary</a>
  <a href="#" class="list-group-item list-group-item-action list-group-item-danger">The Wind in the Willows</a>
</ul>

Adding Content to Bootstrap 4 List Groups

You may need more than a piece of text in your list. Here are some basic use cases that may come in handy.

Adding Icons

If you want to add an icon to the beginning of the list item, you can do so easily by inserting the code for the icon inside the <li> tag. We have used Font Awesome icons in our examples, you can see more about importing and using them in Bootstrap 4 typography tutorial.

<ul class="list-group">
  <li class="list-group-item"><i class="fas fa-male text-info mx-2"></i>David Copperfield</li>
  <li class="list-group-item"><i class="fas fa-venus text-warning mx-2"></i>The Portrait of a Lady</li>
  <li class="list-group-item"><i class="fas fa-gavel text-danger mx-2"></i> The Trial</li>
</ul>

Adding Badges

You can add a counter to list items with the help of badges. In order to align the elements in the list item, you need to transform it into a flex container with the .d-flex utility class. In our example we have used the .justify-content-between class to push the badges to the right and the .align-items-center to align the elements vertically.

<ul class="list-group">
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Crime and Punishment 
    <span class="badge badge-primary badge-pill">10</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    A Clockwork Orange 
    <span class="badge badge-primary badge-pill">14</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">  
    The Age of Innocence
    <span class="badge badge-danger badge-pill">5</span>
  </li>
</ul>

Adding Images

You can also place images inside the list. In our example, we have added thumbnails for books. We have used the list items as flex containers with the .justify-content-between class for positioning.

<ul class="list-group">
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Don Quixote 
    <div class="image-parent">
        <img src="..." class="img-fluid" alt="quixote">
    </div>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    As I Lay Dying 
    <div class="image-parent">
        <img src="..." class="img-fluid" alt="lay">
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">  
    Things Fall Apart
    <div class="image-parent">
        <img src="..." class="img-fluid" alt="things">
  </li>
</ul>

Custom Content

You can add most HTML elements we have learned so far inside a list item. Using the Bootstrap 4 flex utilities, you can easily manage the space inside the list item and position the items. Here is a more complex example:

<ul class="list-group">
  <a href="#" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
    <div class="flex-column">
      Don Quixote 
      <p><small>by Miguel de Cervantes</small></p>
      <span class="badge badge-info badge-pill"> 2 Copies in Stock</span>
    </div>
    <div class="image-parent">
        <img src="..." class="img-fluid" alt="quixote">
    </div>
  </a>
  <a href="#" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
    <div class="flex-column">
      As I Lay Dying 
      <p><small>by William Faulkner</small></p>
      <span class="badge badge-primary badge-pill"> 5 Copies in Stock</span>
    </div>
    <div class="image-parent">
        <img src="..." class="img-fluid" alt="lay">
    </div>
  </a>
  <a href="#" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center disabled">  
    <div class="flex-column">
      Things Fall Apart
      <p><small>by Miguel de Cervantes</small></p>
      <span class="badge badge-danger badge-pill"> 0 Copies in Stock</span>
    </div>
    <div class="image-parent">
        <img src="..." class="img-fluid" alt="things">
    </div>
  </a>
</ul>

Using JavaScript to Create Panels

If you are using actionable panels and you want the item links to toggle content, you can use the JavaScript we have started learning about in Day 11: Bootstrap 4 Navigation Tutorial and Examples.

To add the panels we need the place them in a container with the class .tab-content and give each panel the .tab-pane class. Their visibility is hidden by default so we need to add the .active class to the one we are going to show on page load. There should be a correlation between the link that is active in the .list-group list and the tab that is active in the .tab-content.

The next step is to tie all the links in the .list-groups to the panels in the .tab-content. What we are trying to accomplish is to show the associated panel for a link when it is pressed and hide the previous panel. We ca do this in two ways: using data attributes or via JavaScript calls. We’ll have examples with both.

Via Data Attributes

If you don’t want to write additional JavaScript, you can tie each link to a panel by adding the data-toggle="list" attribute to every link and setting the anchor to the id of the panel href=”[#id]”.

<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-prince-list" data-toggle="list" href="#list-prince" role="tab" aria-controls="prince">The Little Prince</a>
      <a class="list-group-item list-group-item-action" id="list-wild-list" data-toggle="list" href="#list-wild" role="tab" aria-controls="wild">Where the Wild Things Are</a>
      <a class="list-group-item list-group-item-action" id="list-solitude-list" data-toggle="list" href="#list-solitude" role="tab" aria-controls="messages">One Hundred Years of Solitude</a>
    </div>
  </div>
  <div class="col-6">
    <div class="tab-content" id="nav-tabContent">
      <div class="tab-pane active" id="list-prince" role="tabpanel" aria-labelledby="list-prince-list">...</div>
      <div class="tab-pane" id="list-wild" role="tabpanel" aria-labelledby="list-wild-list">...</div>
      <div class="tab-pane" id="list-solitude" role="tabpanel" aria-labelledby="list-solitude-list">...</div>
    </div>
  </div>
</div>

Via JavaScript Calls

If you would rather write JavaScript, then you don’t need the data-toggle="list" attribute. You still need to have ids for every panel and anchors to them. And you need to add a JavaScript event when you click on one of the links in the list that calls the .tab(β€˜show’) function. This function shows the associated panel for the link and hides the previous one.

//html
<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-prince-list" href="#list-prince" role="tab" aria-controls="prince">The Little Prince</a>
      <a class="list-group-item list-group-item-action" id="list-wild-list" href="#list-wild" role="tab" aria-controls="wild">Where the Wild Things Are</a>
      <a class="list-group-item list-group-item-action" id="list-solitude-list" href="#list-solitude" role="tab" aria-controls="messages">One Hundred Years of Solitude</a>
    </div>
  </div>
  <div class="col-6">
    <div class="tab-content" id="nav-tabContent">
      <div class="tab-pane active" id="list-prince" role="tabpanel" aria-labelledby="list-prince-list">...</div>
      <div class="tab-pane" id="list-wild" role="tabpanel" aria-labelledby="list-wild-list">...</div>
      <div class="tab-pane" id="list-solitude" role="tabpanel" aria-labelledby="list-solitude-list">...</div>
    </div>
  </div>
</div>

//js
$('#list-tab a').on('click', function (e) {
  e.preventDefault()
  $(this).tab('show')
});

Advanced JavaScript Behaviour

Fade Effect

You can make the panels appear with a fade effect if you add the .fade class to each .tab-panel. In order for the first panel to be visible, it will also need the .show class (besides the .active class). Here is how the fade effect looks:

<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-prince-list" data-toggle="list" href="#list-prince" role="tab" aria-controls="prince">The Little Prince</a>
      <a class="list-group-item list-group-item-action" id="list-wild-list" data-toggle="list" href="#list-wild" role="tab" aria-controls="wild">Where the Wild Things Are</a>
      <a class="list-group-item list-group-item-action" id="list-solitude-list" data-toggle="list" href="#list-solitude" role="tab" aria-controls="messages">One Hundred Years of Solitude</a>
    </div>
  </div>
  <div class="col-6">
    <div class="tab-content" id="nav-tabContent">
      <div class="tab-pane fade show active" id="list-prince" role="tabpanel" aria-labelledby="list-prince-list">...</div>
      <div class="tab-pane fade" id="list-wild" role="tabpanel" aria-labelledby="list-wild-list">...</div>
      <div class="tab-pane fade" id="list-solitude" role="tabpanel" aria-labelledby="list-solitude-list">...</div>
    </div>
  </div>
</div>

Methods

.tab(β€˜show’)

If you use the .tab('show') method when a .list-item is clicked, the .list-item will become active and the associated panel will become visible. In the example above we have added this method for each .item-list. But we can also call this method individually. For example, here is a button that shows the information about the book β€œWhere the Wild Things Are”:

//html
<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-prince-list" data-toggle="list" href="#list-prince" role="tab" aria-controls="prince">The Little Prince</a>
      <a class="list-group-item list-group-item-action" id="list-wild-list" data-toggle="list" href="#list-wild" role="tab" aria-controls="wild">Where the Wild Things Are</a>
      <a class="list-group-item list-group-item-action" id="list-solitude-list" data-toggle="list" href="#list-solitude" role="tab" aria-controls="messages">One Hundred Years of Solitude</a>
    </div>
  </div>
  <div class="col-6">
    <div class="tab-content" id="nav-tabContent">
      <div class="tab-pane fade show active" id="list-prince" role="tabpanel" aria-labelledby="list-prince-list">...</div>
      <div class="tab-pane fade" id="list-wild" role="tabpanel" aria-labelledby="list-wild-list">...</div>
      <div class="tab-pane fade" id="list-solitude" role="tabpanel" aria-labelledby="list-solitude-list">...</div>
    </div>
  </div>
</div>

<button type="button" class="btn btn-success btn-sm mt-3" id="show-wild">Show Wild</button>

//js
$('#show-wild').on('click', function () {
  $('#list-wild-list').tab('show');
})

Events

When panels change, there are a series of events that go on. We will present each one, its order and its behaviour. They are the same events that we described for tabs inΒ Day 11: Bootstrap 4 Navigation Tutorial and Examples, so may already be familiar with them.

Order Event Target Description
1 hide.bs.tab the current active 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.
2 show.bs.tab the to-be-shown 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.
3 hidden.bs.tab on the previous active tab, the same one as for the hide.bs.tab event 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.
4 shown.bs.tab on the newly-active just-shown tab, the same one as for the show.bs.tab event 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.

If no tab was already active, the hide.bs.tab and hidden.bs.tab events will not be fired.

We have created an example that uses the shown.bs.tab method and color the .list-items you have previously visited to light blue:

//html
<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-prince-list" data-toggle="list" href="#list-prince" role="tab" aria-controls="prince">The Little Prince</a>
      <a class="list-group-item list-group-item-action" id="list-wild-list" data-toggle="list" href="#list-wild" role="tab" aria-controls="wild">Where the Wild Things Are</a>
      <a class="list-group-item list-group-item-action" id="list-solitude-list" data-toggle="list" href="#list-solitude" role="tab" aria-controls="messages">One Hundred Years of Solitude</a>
    </div>
  </div>
  <div class="col-6">
    <div class="tab-content" id="nav-tabContent">
      <div class="tab-pane fade show active" id="list-prince" role="tabpanel" aria-labelledby="list-prince-list">...</div>
      <div class="tab-pane fade" id="list-wild" role="tabpanel" aria-labelledby="list-wild-list">...</div>
      <div class="tab-pane fade" id="list-solitude" role="tabpanel" aria-labelledby="list-solitude-list">...</div>
    </div>
  </div>
</div>

//js
$('a[data-toggle="list"]').on('shown.bs.tab', function (e) {
  $(e.target).removeClass( "light-blue" );
  $(e.relatedTarget).addClass( "light-blue" );
})

This is all for today! I hope you have enjoyed learning about list and list groups. All the code we have used in this article is available on CodePen where you can fork and edit it. Let me know if you run into any kind of trouble when trying your list! Have a nice day and see you again tomorrow πŸ™‚

Further Reading

If you have some time left, here are some useful links that you can read for further reference:

bootstrap-4-lists-end

Photo credit to Juna Wang for her shot.

Photo credit for featured image to Sara Geci for her shot.

Sharing is caring!

Cristina Conacel

Cristina is a web developer and the owner of BootstrapBay. She likes foxes, clean design, writing blog posts and creating themes that are useful to other developers.