Pills

Bootstrap 5 Pills component

Pills are quasi-navigation components which can highly improve website clarity and increase user experience.

Note: Read the API tab to find all available options and advanced customization

Required ES init: Tab *
* UMD autoinits are enabled by default. This means that you don't need to initialize the component manually. However if you are using MDBootstrap ES format then you should pass the required components to the initMDB method.

Basic example

Basic pills are divided into 2 main sections - Pills navs (containing nav-items) and Pills content (containing tab-panes).

Use id and href attribute to connect pills navs with pills content.

In the example below Tab 1 uses href="#ex1-pills-1" in the first nav-link element to connect it with the first tab-pane which has an ID ex1-pills-1.

Tab 1 content
Tab 2 content
Tab 3 content
        
            
          <!-- Pills navs -->
          <ul class="nav nav-pills mb-3" id="ex1" role="tablist">
            <li class="nav-item" role="presentation">
              <a
                data-mdb-pill-init
                class="nav-link active"
                id="ex1-tab-1"
                href="#ex1-pills-1"
                role="tab"
                aria-controls="ex1-pills-1"
                aria-selected="true"
                >Tab 1</a
              >
            </li>
            <li class="nav-item" role="presentation">
              <a
                data-mdb-pill-init
                class="nav-link"
                id="ex1-tab-2"
                href="#ex1-pills-2"
                role="tab"
                aria-controls="ex1-pills-2"
                aria-selected="false"
                >Tab 2</a
              >
            </li>
            <li class="nav-item" role="presentation">
              <a
                data-mdb-pill-init
                class="nav-link"
                id="ex1-tab-3"
                href="#ex1-pills-3"
                role="tab"
                aria-controls="ex1-pills-3"
                aria-selected="false"
                >Tab 3</a
              >
            </li>
          </ul>
          <!-- Pills navs -->

          <!-- Pills content -->
          <div class="tab-content" id="ex1-content">
            <div
              class="tab-pane fade show active"
              id="ex1-pills-1"
              role="tabpanel"
              aria-labelledby="ex1-tab-1"
            >
              Tab 1 content
            </div>
            <div class="tab-pane fade" id="ex1-pills-2" role="tabpanel" aria-labelledby="ex1-tab-2">
              Tab 2 content
            </div>
            <div class="tab-pane fade" id="ex1-pills-3" role="tabpanel" aria-labelledby="ex1-tab-3">
              Tab 3 content
            </div>
          </div>
          <!-- Pills content -->
        
        
    
        
            
          // Initialization for ES Users
          import { Tab, initMDB } from "mdb-ui-kit";

          initMDB({ Tab });
        
        
    

Fill and justify

Force your .nav's contents to extend the full available width one of two modifier classes.

Fill

To proportionately fill all available space with your .nav-items, use .nav-fill. Notice that all horizontal space is occupied, but not every nav item has the same width.

        
            
            <!-- Pills navs -->
            <ul class="nav nav-pills nav-fill mb-3" id="ex1" role="tablist">
              <li class="nav-item" role="presentation">
                <a
                  data-mdb-pill-init
                  class="nav-link active"
                  id="ex2-tab-1"
                  href="#ex2-pills-1"
                  role="tab"
                  aria-controls="ex2-pills-1"
                  aria-selected="true"
                  >Link</a
                >
              </li>
              <li class="nav-item" role="presentation">
                <a
                  data-mdb-pill-init
                  class="nav-link"
                  id="ex2-tab-2"
                  href="#ex2-pills-2"
                  role="tab"
                  aria-controls="ex2-pills-2"
                  aria-selected="false"
                  >Very very very very long link</a
                >
              </li>
              <li class="nav-item" role="presentation">
                <a
                  data-mdb-pill-init
                  class="nav-link"
                  id="ex2-tab-3"
                  href="#ex2-pills-3"
                  role="tab"
                  aria-controls="ex2-pills-3"
                  aria-selected="false"
                  >Another link</a
                >
              </li>
            </ul>
            <!-- Pills navs -->

            <!-- Pills content -->
            <div class="tab-content" id="ex2-content">
              <div
                class="tab-pane fade show active"
                id="ex2-pills-1"
                role="tabpanel"
                aria-labelledby="ex2-tab-1"
              >
                Tab 1 content
              </div>
              <div
                class="tab-pane fade"
                id="ex2-pills-2"
                role="tabpanel"
                aria-labelledby="ex2-tab-2"
              >
                Tab 2 content
              </div>
              <div
                class="tab-pane fade"
                id="ex2-pills-3"
                role="tabpanel"
                aria-labelledby="ex2-tab-3"
              >
                Tab 3 content
              </div>
            </div>
            <!-- Pills content -->
          
        
    
        
            
            // Initialization for ES Users
            import { Tab, initMDB } from "mdb-ui-kit";

            initMDB({ Tab });
          
        
    

Justify

For equal-width elements, use .nav-justified. All horizontal space will be occupied by nav links, but unlike the .nav-fill above, every nav item will be the same width.

        
            
            <!-- Pills navs -->
            <ul class="nav nav-pills nav-justified mb-3" id="ex1" role="tablist">
              <li class="nav-item" role="presentation">
                <a
                  data-mdb-pill-init
                  class="nav-link active"
                  id="ex3-tab-1"
                  href="#ex3-pills-1"
                  role="tab"
                  aria-controls="ex3-pills-1"
                  aria-selected="true"
                  >Link</a
                >
              </li>
              <li class="nav-item" role="presentation">
                <a
                  data-mdb-pill-init
                  class="nav-link"
                  id="ex3-tab-2"
                  href="#ex3-pills-2"
                  role="tab"
                  aria-controls="ex3-pills-2"
                  aria-selected="false"
                  >Very very very very long link</a
                >
              </li>
              <li class="nav-item" role="presentation">
                <a
                  data-mdb-pill-init
                  class="nav-link"
                  id="ex3-tab-3"
                  href="#ex3-pills-3"
                  role="tab"
                  aria-controls="ex3-pills-3"
                  aria-selected="false"
                  >Another link</a
                >
              </li>
            </ul>
            <!-- Pills navs -->

            <!-- Pills content -->
            <div class="tab-content" id="ex2-content">
              <div
                class="tab-pane fade show active"
                id="ex3-pills-1"
                role="tabpanel"
                aria-labelledby="ex3-tab-1"
              >
                Tab 1 content
              </div>
              <div
                class="tab-pane fade"
                id="ex3-pills-2"
                role="tabpanel"
                aria-labelledby="ex3-tab-2"
              >
                Tab 2 content
              </div>
              <div
                class="tab-pane fade"
                id="ex3-pills-3"
                role="tabpanel"
                aria-labelledby="ex3-tab-3"
              >
                Tab 3 content
              </div>
            </div>
            <!-- Pills content -->
          
        
    
        
            
            // Initialization for ES Users
            import { Tab, initMDB } from "mdb-ui-kit";

            initMDB({ Tab });
          
        
    

Vertical

Stack your navigation by changing the flex item direction with the .flex-column utility. Need to stack them on some viewports but not others? Use the responsive versions (e.g., .flex-sm-column).

For proper layout, you may also need to use grid to adjust navs and content.

Home content
Profile content
Messages content
        
            
          <div class="row">
            <div class="col-3">
              <!-- Tab navs -->
              <div
                class="nav flex-column nav-pills text-center"
                id="v-pills-tab"
                role="tablist"
                aria-orientation="vertical"
              >
                <a
                  data-mdb-pill-init
                  class="nav-link active"
                  id="v-pills-home-tab"
                  href="#v-pills-home"
                  role="tab"
                  aria-controls="v-pills-home"
                  aria-selected="true"
                  >Home</a
                >
                <a
                  data-mdb-pill-init
                  class="nav-link"
                  id="v-pills-profile-tab"
                  href="#v-pills-profile"
                  role="tab"
                  aria-controls="v-pills-profile"
                  aria-selected="false"
                  >Profile</a
                >
                <a
                  data-mdb-pill-init
                  class="nav-link"
                  id="v-pills-messages-tab"
                  href="#v-pills-messages"
                  role="tab"
                  aria-controls="v-pills-messages"
                  aria-selected="false"
                  >Messages</a
                >
              </div>
              <!-- Tab navs -->
            </div>

            <div class="col-9">
              <!-- Tab content -->
              <div class="tab-content" id="v-pills-tabContent">
                <div
                  class="tab-pane fade show active"
                  id="v-pills-home"
                  role="tabpanel"
                  aria-labelledby="v-pills-home-tab"
                >
                  Home content
                </div>
                <div
                  class="tab-pane fade"
                  id="v-pills-profile"
                  role="tabpanel"
                  aria-labelledby="v-pills-profile-tab"
                >
                  Profile content
                </div>
                <div
                  class="tab-pane fade"
                  id="v-pills-messages"
                  role="tabpanel"
                  aria-labelledby="v-pills-messages-tab"
                >
                  Messages content
                </div>
              </div>
              <!-- Tab content -->
            </div>
          </div>
        
        
    
        
            
          // Initialization for ES Users
          import { Tab, initMDB } from "mdb-ui-kit";

          initMDB({ Tab });
        
        
    

Pills with icons

Use one of many available icons and add it to the pills. See the icon docs to explore all the available icons.

Tab 1 content
Tab 2 content
Tab 3 content
        
            
  
        <!-- Tabs navs -->
        <ul class="nav nav-pills mb-3" id="ex-with-icons" role="tablist">
          <li class="nav-item" role="presentation">
            <a data-mdb-pill-init class="nav-link active" id="ex-with-icons-tab-1" href="#ex-with-icons-tabs-1" role="tab"
            aria-controls="ex-with-icons-tabs-1" aria-selected="true"><i class="fas fa-chart-pie fa-fw me-2"></i>Sales</a>
          </li>
          <li class="nav-item" role="presentation">
            <a data-mdb-pill-init class="nav-link" id="ex-with-icons-tab-2" href="#ex-with-icons-tabs-2" role="tab"
              aria-controls="ex-with-icons-tabs-2" aria-selected="false"><i class="fas fa-chart-line fa-fw me-2"></i>Subscriptions</a>
          </li>
          <li class="nav-item" role="presentation">
            <a data-mdb-pill-init class="nav-link" id="ex-with-icons-tab-3" href="#ex-with-icons-tabs-3" role="tab"
              aria-controls="ex-with-icons-tabs-3" aria-selected="false"><i class="fas fa-cogs fa-fw me-2"></i>Settings</a>
          </li>
        </ul>
        <!-- Tabs navs -->
    
        <!-- Tabs content -->
        <div class="tab-content" id="ex-with-icons-content">
          <div class="tab-pane fade show active" id="ex-with-icons-tabs-1" role="tabpanel" aria-labelledby="ex-with-icons-tab-1">
            Tab 1 content
          </div>
          <div class="tab-pane fade" id="ex-with-icons-tabs-2" role="tabpanel" aria-labelledby="ex-with-icons-tab-2">
            Tab 2 content
          </div>
          <div class="tab-pane fade" id="ex-with-icons-tabs-3" role="tabpanel" aria-labelledby="ex-with-icons-tab-3">
            Tab 3 content
          </div>
        </div>
        <!-- Tabs content -->
  
            
        
    
        
            
              // Initialization for ES Users
              import { Tab, initMDB } from "mdb-ui-kit";
    
              initMDB({ Tab });
            
        
    

Pills with buttons

Dynamic tabbed interfaces, as described in the WAI ARIA Authoring Practices, require role="tablist", role="tab", role="tabpanel", and additional aria- attributes in order to convey their structure, functionality and current state to users of assistive technologies (such as screen readers). As a best practice, we recommend using <button> elements for the tabs, as these are controls that trigger a dynamic change, rather than links that navigate to a new page or location.

Tab 1 content
Tab 2 content
Tab 3 content
        
            
          <ul class="nav nav-pills mb-3" id="pills-tab2" role="tablist">
            <li class="nav-item" role="presentation">
              <button
                data-mdb-pill-init
                class="nav-link active"
                id="pills-home-tab2"
                data-mdb-target="#pills-home2"
                type="button"
                role="tab"
                aria-controls="pills-home"
                aria-selected="true"
              >
                Home
              </button>
            </li>
            <li class="nav-item" role="presentation">
              <button
                data-mdb-pill-init
                class="nav-link"
                id="pills-profile-tab2"
                data-mdb-target="#pills-profile2"
                type="button"
                role="tab"
                aria-controls="pills-profile"
                aria-selected="false"
              >
                Profile
              </button>
            </li>
            <li class="nav-item" role="presentation">
              <button
                data-mdb-pill-init
                class="nav-link"
                id="pills-contact-tab2"
                data-mdb-target="#pills-contact2"
                type="button"
                role="tab"
                aria-controls="pills-contact"
                aria-selected="false"
              >
                Contact
              </button>
            </li>
          </ul>
          <div class="tab-content" id="pills-tabContent2">
            <div
              class="tab-pane fade show active"
              id="pills-home2"
              role="tabpanel"
              aria-labelledby="pills-home-tab2"
            >
              Tab 1 content
            </div>
            <div
              class="tab-pane fade"
              id="pills-profile2"
              role="tabpanel"
              aria-labelledby="pills-profile-tab2"
            >
              Tab 2 content
            </div>
            <div
              class="tab-pane fade"
              id="pills-contact2"
              role="tabpanel"
              aria-labelledby="pills-contact-tab2"
            >
              Tab 3 content
            </div>
          </div>
        
        
    
        
            
          // Initialization for ES Users
          import { Tab, initMDB } from "mdb-ui-kit";

          initMDB({ Tab });
        
        
    

Pills - API


Import

Importing components depends on how your application works. If you intend to use the MDBootstrap ES format, you must first import the component and then initialize it with the initMDB method. If you are going to use the UMD format, just import the mdb-ui-kit package.

        
            
            import { Tab, initMDB } from "mdb-ui-kit";
  
            initMDB({ Tab });
          
        
    
        
            
            import 'mdb-ui-kit';
          
        
    

Usage

Regarding accessibility

If you’re using navs to provide a navigation bar, be sure to add a role="navigation" to the most logical parent container of the <ul>, or wrap a <nav> element around the whole navigation. Do not add the role to the <ul> itself, as this would prevent it from being announced as an actual list by assistive technologies.

Note that navigation bars, even if visually styled as pills with the .nav-pills class, should not be given role="tablist", role="tab" or role="tabpanel" attributes. These are only appropriate for dynamic tabbed interfaces, as described in the WAI ARIA Authoring Practices. The aria-current attribute is not necessary on dynamic tabbed interfaces since our JavaScript handles the selected state by adding aria-selected="true" on the active tab.

Via data attributes

Using the Pills component doesn't require any additional JavaScript code - simply add data-mdb-pill-init attribute to every .nav-link and use other data attributes to set all options. For ES format, you must first import and call the initMDB method.

        
            
          <!-- Nav pills -->
          <ul class="nav nav-pills" id="myTab" role="tablist">
            <li class="nav-item" role="presentation">
              <a
                data-mdb-pill-init
                class="nav-link active"
                id="home-tab"
                href="#home"
                role="tab"
                aria-controls="home"
                aria-selected="true"
                >Home</a
              >
            </li>
            <li class="nav-item" role="presentation">
              <a
                data-mdb-pill-init
                class="nav-link"
                id="profile-tab"
                href="#profile"
                role="tab"
                aria-controls="profile"
                aria-selected="false"
                >Profile</a
              >
            </li>
            <li class="nav-item" role="presentation">
              <a
                data-mdb-pill-init
                class="nav-link"
                id="messages-tab"
                href="#messages"
                role="tab"
                aria-controls="messages"
                aria-selected="false"
                >Messages</a
              >
            </li>
            <li class="nav-item" role="presentation">
              <a
                data-mdb-pill-init
                class="nav-link"
                id="settings-tab"
                href="#settings"
                role="tab"
                aria-controls="settings"
                aria-selected="false"
                >Settings</a
              >
            </li>
          </ul>

          <!-- Tab panes -->
          <div class="tab-content">
            <div class="tab-pane active" id="home" role="tabpanel" aria-labelledby="home-tab">
              ...
            </div>
            <div class="tab-pane" id="profile" role="tabpanel" aria-labelledby="profile-tab">
              ...
            </div>
            <div class="tab-pane" id="messages" role="tabpanel" aria-labelledby="messages-tab">
              ...
            </div>
            <div class="tab-pane" id="settings" role="tabpanel" aria-labelledby="settings-tab">
              ...
            </div>
          </div>
        
        
    

Via JavaScript

Enable tabbable pills via JavaScript (each tab needs to be activated individually):

        
            
          const triggerPillList = document.querySelectorAll('.nav-item a')

          triggerPillList.forEach((triggerEl) => {
            const pillTrigger = new Tab(triggerEl)

            triggerEl.addEventListener('click', (e) => {
              e.preventDefault()
              pillTrigger.show()
            })
          })
        
        
    
        
            
          const triggerPillList = document.querySelectorAll('.nav-item a')

          triggerPillList.forEach((triggerEl) => {
            const pillTrigger = new mdb.Tab(triggerEl)
            
            triggerEl.addEventListener('click', (e) => {
              e.preventDefault()
              pillTrigger.show()
            })
          })
        
        
    

You can activate individual pills in several ways:

        
            
          const triggerEl = document.querySelector('#myTab a[href="#profile"]')
          Tab.getInstance(triggerEl).show() // Select tab by name

          const triggerFirstPillEl = document.querySelector('#myTab li:first-child a')
          Tab.getInstance(triggerFirstPillEl).show() // Select first tab
        
        
    
        
            
          const triggerEl = document.querySelector('#myTab a[href="#profile"]')
          mdb.Tab.getInstance(triggerEl).show() // Select tab by name

          const triggerFirstPillEl = document.querySelector('#myTab li:first-child a')
          mdb.Tab.getInstance(triggerFirstPillEl).show() // Select first tab
        
        
    

Via jQuery

Note: By default, MDB does not include jQuery and you have to add it to the project on your own.

        
            
          $('.example-class').tab();
        
        
    

Methods

Asynchronous methods and transitions:
All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

Name Description Example
show Selects the given tab and shows its associated pane. Any other tab that was previously selected becomes unselected and its associated pane is hidden. Returns to the caller before the tab pane has actually been shown (i.e. before the shown.mdb.tab event occurs). instance.show()
dispose Destroys an element’s tab. instance.dispose()
getInstance Static method which allows you to get the tab instance associated to a DOM element. Tab.getInstance(someTabTriggerEl)
        
            
          const someTabTriggerEl = document.querySelector('#someTabTrigger')
          const tab = new Tab(someTabTriggerEl) 
          tab.show()
        
        
    
        
            
        const someTabTriggerEl = document.querySelector('#someTabTrigger')
        const tab = new mdb.Tab(someTabTriggerEl) 
        tab.show()
      
        
    

Events

When showing a new tab, the events fire in the following order:

  1. hide.mdb.tab (on the current active tab)
  2. show.mdb.tab (on the to-be-shown tab)
  3. hidden.mdb.tab (on the previous active tab, the same one as for the hide.mdb.tab event)
  4. shown.mdb.tab (on the newly-active just-shown tab, the same one as for the show.mdb.tab event)

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

Event type Description
show.mdb.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.mdb.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.
hide.mdb.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.mdb.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.
        
            
          const tabEl = document.querySelector('a[data-mdb-pill-init]')
          tabEl.addEventListener('shown.mdb.tab', (e) => {
            console.log(e.target) // newly activated tab
            console.log(e.relatedTarget) // previous active tab
          })
        
        
    

CSS variables

As part of MDB’s evolving CSS variables approach, pills now use local CSS variables for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

Pills CSS variables are in different classes which belong to this component. To make it easier to use them, you can find below all of the used CSS variables.

        
            
        // .nav
        --#{$prefix}nav-link-disabled-color: #{$nav-link-disabled-color};

        // .nav-pills
        // .nav-link
        --#{$prefix}nav-pills-link-border-radius: #{$nav-pills-link-border-radius};
        --#{$prefix}nav-pills-link-font-size: #{$nav-pills-link-font-size};
        --#{$prefix}nav-pills-link-padding-top: #{$nav-pills-link-padding-top};
        --#{$prefix}nav-pills-link-padding-bottom: #{$nav-pills-link-padding-bottom};
        --#{$prefix}nav-pills-link-padding-x: #{$nav-pills-link-padding-x};
        --#{$prefix}nav-pills-link-line-height: #{$nav-pills-link-line-height};
        --#{$prefix}nav-pills-link-hover-bg: #{$nav-pills-link-hover-bg};
        --#{$prefix}nav-pills-link-font-weight: #{$nav-pills-link-font-weight};
        --#{$prefix}nav-pills-link-color: #{$nav-pills-link-color};
        --#{$prefix}nav-pills-margin: #{$nav-pills-margin};
        
        // .nav-link.active,
        // .show > .nav-link
        --#{$prefix}nav-pills-link-active-bg: #{$nav-pills-link-active-bg};
        --#{$prefix}nav-pills-link-active-color: #{$nav-pills-link-active-color};
        
        
    

SCSS variables

        
            
        $nav-link-transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out;
        $nav-link-disabled-color: $gray-600;

        $nav-pills-border-radius: $border-radius;

        $nav-pills-margin: 0.5rem;
        $nav-pills-link-border-radius: 0.25rem;
        $nav-pills-link-font-size: $nav-tabs-link-font-size;
        $nav-pills-link-padding-top: $nav-tabs-link-padding-top;
        $nav-pills-link-padding-bottom: $nav-tabs-link-padding-bottom;
        $nav-pills-link-padding-x: $nav-tabs-link-padding-x;
        $nav-pills-link-line-height: 1;
        $nav-pills-link-background-color: $nav-tabs-link-hover-background-color;
        $nav-pills-link-font-weight: $nav-tabs-link-font-weight;

        $nav-pills-link-color: $nav-tabs-link-color;
        $nav-pills-link-hover-bg: $nav-tabs-link-hover-bgc;

        $nav-pills-link-active-bg: var(--#{$prefix}primary-bg-subtle);
        $nav-pills-link-active-color: var(--#{$prefix}primary-text-emphasis);