Report an issueEdit this page

Navs

Navigation available in Bootstrap share general markup and styles, from the base <b-nav> class to the active and disabled states. Swap modifier props to switch between each style.

<div>
  <b-nav>
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item>Another Link</b-nav-item>
    <b-nav-item disabled>Disabled</b-nav-item>
  </b-nav>
</div>

<!-- b-nav.vue -->

Overview

The base <b-nav> component is built with flexbox and provides a strong foundation for building all types of navigation components. It includes some style overrides (for working with lists), some link padding for larger hit areas, and basic disabled styling. No active states are included in the base nav.

<b-nav> supports the following child components:

  • <b-nav-item> for actionable links (or router-links)
  • <b-nav-item-dropdown> for dropdowns
  • <b-nav-text> for plain text content
  • <b-nav-form> for inline forms

Two style variations are supported: tabs and pills, which support active state styling. These variants are mutually exclusive - use only one style or the other.

Tab style

Make the nav look like tabs by setting the tabs prop.

<div>
  <b-nav tabs>
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item>Another Link</b-nav-item>
    <b-nav-item disabled>Disabled</b-nav-item>
  </b-nav>
</div>

<!-- b-nav-tabs.vue -->

Pill style

Use the pill style by setting the pills prop.

<div>
  <b-nav pills>
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item>Another Link</b-nav-item>
    <b-nav-item disabled>Disabled</b-nav-item>
  </b-nav>
</div>

<!-- b-nav-pills.vue -->

Small

Make the nav smaller by setting the small prop.

<div>
  <b-nav small>
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item>Another Link</b-nav-item>
    <b-nav-item disabled>Disabled</b-nav-item>
  </b-nav>
</div>

<!-- b-nav-small.vue -->

Fill and justify

Force your <b-nav> content to extend the full available width.

Fill

To proportionately fill all available space with your <b-nav-item> components, set the fill prop. Notice that all horizontal space is occupied, but not every nav item has the same width.

<div>
  <b-nav tabs fill>
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item>Link with a long name </b-nav-item>
    <b-nav-item disabled>Disabled</b-nav-item>
  </b-nav>
</div>

<!-- b-nav-fill.vue -->

Justified

For equal-width elements, set the justified prop instead. All horizontal space will be occupied by nav links, but unlike fill above, every <b-nav-item> will be the same width.

<div>
  <b-nav tabs justified>
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item>Link with a long name </b-nav-item>
    <b-nav-item disabled>Disabled</b-nav-item>
  </b-nav>
</div>

<!-- b-nav-justified.vue -->

Alignment

To align your <b-nav-item> components, use the align prop. Available values are left, center and right.

<div>
  <b-nav tabs align="center">
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item>Link with a long name </b-nav-item>
    <b-nav-item disabled>Disabled</b-nav-item>
  </b-nav>
</div>

<!-- b-nav-alignment.vue -->

Vertical variation

By default <b-nav> appear on a horizontal line. Stack your navigation by setting the vertical prop.

<div>
  <b-nav vertical class="w-25">
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item>Another Link</b-nav-item>
    <b-nav-item disabled>Disabled</b-nav-item>
  </b-nav>
</div>

<!-- b-nav-vertical.vue -->

Use <b-nav-item-dropdown> to place dropdown items within your nav.

<div>
  <b-nav pills>
    <b-nav-item active>Active</b-nav-item>
    <b-nav-item>Link</b-nav-item>
    <b-nav-item-dropdown
      id="my-nav-dropdown"
      text="Dropdown"
      toggle-class="nav-link-custom"
      right
    >
      <b-dropdown-item>One</b-dropdown-item>
      <b-dropdown-item>Two</b-dropdown-item>
      <b-dropdown-divider></b-dropdown-divider>
      <b-dropdown-item>Three</b-dropdown-item>
    </b-nav-item-dropdown>
  </b-nav>
</div>

<!-- b-nav-dropdown.vue -->

Sometimes you want to add your own class names to the generated dropdown toggle button, that by default have the classes nav-link and dropdown-toggle. Use the toggle-class prop to add them (like above) which will produce something like:

<li id="my-nav-dropdown" class="nav-item b-nav-dropdown dropdown">
  <a
    href="#"
    id="my-nav-dropdown__BV_button_"
    aria-haspopup="true"
    aria-expanded="false"
    class="nav-link dropdown-toggle nav-link-custom"
  ></a>
  ...
</li>

Refer to <b-dropdown> for a list of supported sub-components.

Optionally scoped default slot

The dropdown default slot is optionally scoped with the following scope available:

Property or Method Description
hide() Can be used to close the dropdown menu. Accepts an optional boolean argument, which if true returns focus to the toggle button

Lazy dropdown

By default, <b-nav-item-dropdown> renders the menu contents in the DOM even when the menu is not shown. When there are a large number of dropdowns rendered on the same page, performance could be impacted due to larger overall memory utilization. You can instruct <b-nav-item-dropdown> to render the menu contents only when it is shown by setting the lazy prop to true.

Nav text content

Use the <b-nav-text> child component to place plain text content into the nav:

<div>
  <b-nav >
    <b-nav-item href="#1">Link 1</b-nav-item>
    <b-nav-item href="#2">Link 2</b-nav-item>
    <b-nav-text>Plain text</b-nav-text>
  </b-nav>
</div>

<!-- b-nav-text.vue -->

Use the <b-nav-form> child component to place an inline form into the nav:

<div>
  <b-nav pills>
    <b-nav-item href="#1" active>Link 1</b-nav-item>
    <b-nav-item href="#2">Link 2</b-nav-item>
    <b-nav-form @submit.stop.prevent="alert('Form Submitted')">
      <b-form-input aria-label="Input" class="mr-1"></b-form-input>
      <b-button type="submit">Ok</b-button>
    </b-nav-form>
  </b-nav>
</div>

<!-- b-nav-form.vue -->

Refer to the <b-form> inline documentation for additional details on placing form controls.

Tabbed local content support

See the <b-tabs> component for creating tabbable panes of local content (not suited for navigation).

Card integration

Use a <b-nav> in a <b-card> header, by enabling the card-header prop on <b-nav> and setting either the pills or tabs props:

Tabs style:

<div>
  <b-card title="Card Title" no-body>
    <b-card-header header-tag="nav">
      <b-nav card-header tabs>
        <b-nav-item active>Active</b-nav-item>
        <b-nav-item>Inactive</b-nav-item>
        <b-nav-item disabled>Disabled</b-nav-item>
      </b-nav>
    </b-card-header>

    <b-card-body class="text-center">
      <b-card-text>
        With supporting text below as a natural lead-in to additional content.
      </b-card-text>

      <b-button variant="primary">Go somewhere</b-button>
    </b-card-body>
  </b-card>
</div>

<!-- nav-card-tabs.vue -->

Pill style:

<div>
  <b-card title="Card Title" no-body>
    <b-card-header header-tag="nav">
      <b-nav card-header pills>
        <b-nav-item active>Active</b-nav-item>
        <b-nav-item>Inactive</b-nav-item>
        <b-nav-item disabled>Disabled</b-nav-item>
      </b-nav>
    </b-card-header>

    <b-card-body class="text-center">
      <b-card-text>
        With supporting text below as a natural lead-in to additional content.
      </b-card-text>

      <b-button variant="primary">Go somewhere</b-button>
    </b-card-body>
  </b-card>
</div>

<!-- nav-card-pills.vue -->

Plain style:

The card-header prop is only needed when you are applying tabs or pills style. Note that Bootstrap v4 SCSS does not have special styling for active state plain style nav items.

<div>
  <b-card title="Card Title" no-body>
    <b-card-header header-tag="nav">
      <b-nav>
        <b-nav-item active>Active</b-nav-item>
        <b-nav-item>Inactive</b-nav-item>
        <b-nav-item disabled>Disabled</b-nav-item>
      </b-nav>
    </b-card-header>

    <b-card-body class="text-center">
      <b-card-text>
        With supporting text below as a natural lead-in to additional content.
      </b-card-text>

      <b-button variant="primary">Go somewhere</b-button>
    </b-card-body>
  </b-card>
</div>

<!-- nav-card-plain.vue -->

The card-header prop has no styling effect if the <b-nav> is in vertical mode.

Using with Vue Router

Have your card <b-nav> control vue router nested routes via <router-view> or <nuxt-child> components, to created tabbed content that changes with route URL:

// On page with route `/some/route`
<div>
  <b-card title="Card Title" no-body>
    <b-card-header header-tag="nav">
      <b-nav card-header tabs>
        <!-- <b-nav-item>'s with child routes. Note the trailing slash on the first <b-nav-item> -->
        <b-nav-item to="/some/route/" exact exact-active-class="active">Active</b-nav-item>
        <b-nav-item to="/some/route/foo" exact exact-active-class="active">Foo</b-nav-item>
        <b-nav-item to="/some/route/bar" exact exact-active-class="active">Bar</b-nav-item>
      </b-nav>
    </b-card-header>

    <b-card-body>
      <!-- Child route gets rendered in <router-view> or <nuxt-child> -->
      <router-view></router-view>
      <!-- Or if using Nuxt.js
      <nuxt-child></nuxt-child>
      -->
    </b-card-body>
  </b-card>
</div>

Note: Vue Router does not support defining active routes with hashes (#), which is why you must define the "tab" content as child routes.

Example router config for above:

const routes = [
  {
    path: '/some/route',
    // We don't provide a name on this parent route, but rather
    // set the name on the default child route instead
    // name: 'some-route',
    component: SomeRouteComponent,
    // Child route "tabs"
    children: [
      // Note we provide the above parent route name on the default child tab
      // route to ensure this tab is rendered by default when using named routes
      { path: '', component: DefaultTabComponent, name: 'some-route' },
      { path: 'foo', component: FooTabComponent },
      { path: 'bar', component: BarTabComponent }
    ]
  }
]

One can also use Vue Router named routes and/or route params instead of path based routes.

For more details see:

Accessibility

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

When using a <b-nav-item-dropdown> in your <b-nav>, be sure to assign a unique id prop value to the <b-nav-dropdown> so that the appropriate aria-* attributes can be automatically generated.

Tabbed interface accessibility

Note that navigation bars, even if visually styled as tabs, should not be given role="tablist", role="tab" or role="tabpanel" attributes. These are only appropriate for tabbed interfaces that do not change the URL or $route, as described in the WAI ARIA Authoring Practices. See <b-tabs> for dynamic tabbed interfaces that are compliant with WAI ARIA.

Tabbed interfaces should avoid using dropdown menus, as this causes both usability and accessibility issues:

  • From a usability perspective, the fact that the currently displayed tab’s trigger element is not immediately visible (as it’s inside the closed dropdown menu) can cause confusion.
  • From an accessibility point of view, there is currently no sensible way to map this sort of construct to a standard WAI ARIA pattern, meaning that it cannot be easily made understandable to users of assistive technologies.

See also

  • <b-tabs> to create tabbable panes of local content, even via dropdown menus.
  • <b-navbar> a wrapper that positions branding, navigation, and other elements in a concise header.
  • <b-dropdown> for sub-components that you can place inside <b-nav-item-dropdown>
  • Router Link Support reference for information about router-link specific props available on <b-nav-item>

Component reference

<b-nav>

Functional component
View source

Properties

PropertyTypeDefaultDescription
tag
String'ul'Specify the HTML tag to render instead of the default tag
fill
BooleanfalseProportionately fills all horizontal space with nav items. All horizontal space is occupied, but not every nav item has the same width
justified
BooleanfalseFills all horizontal space with nav items, but unlike 'fill', every nav item will be the same width
align
StringAlign the nav items in the nav: 'start' (or 'left'), 'center', 'end' (or 'right')
tabs
BooleanfalseRenders the nav items with the appearance of tabs
pills
BooleanfalseRenders the nav items with the appearance of pill buttons
vertical
BooleanfalseRenders the nav vertically
small
BooleanfalseMakes the nav smaller
card-header
v2.0.0+ 		BooleanfalseSet this prop when the nav is placed inside a card header

<b-nav-item>

Functional component
View source

Properties

Property (Click to sort Ascending)TypeDefaultDescription
href
StringnullDenotes the target URL of the link for standard a links
rel
StringnullSets the 'rel' attribute on the rendered link
target
String'_self'Sets the 'target' attribute on the rendered link
active
BooleanfalseWhen set to 'true', places the component in the active state with active styling
disabled
BooleanfalseWhen set to 'true', disables the component's functionality and places it in a disabled state
to
String or Objectnullrouter-link prop: Denotes the target route of the link. When clicked, the value of the to prop will be passed to router.push() internally, so the value can be either a string or a Location descriptor object
append
Booleanfalserouter-link prop: Setting append prop always appends the relative path to the current path
replace
Booleanfalserouter-link prop: Setting the replace prop will call 'router.replace()' instead of 'router.push()' when clicked, so the navigation will not leave a history record
event
String or Array'click'router-link prop: Specify the event that triggers the link. In most cases you should leave this as the default
active-class
Stringrouter-link prop: Configure the active CSS class applied when the link is active. Typically you will want to set this to class name 'active'
exact
Booleanfalserouter-link prop: The default active class matching behavior is inclusive match. Setting this prop forces the mode to exactly match the route
exact-active-class
Stringrouter-link prop: Configure the active CSS class applied when the link is active with exact match. Typically you will want to set this to class name 'active'
router-tag
String'a'router-link prop: Specify which tag to render, and it will still listen to click events for navigation. 'router-tag' translates to the tag prop on the final rendered router-link. Typically you should use the default value
no-prefetch
Booleanfalsenuxt-link prop: To improve the responsiveness of your Nuxt.js applications, when the link will be displayed within the viewport, Nuxt.js will automatically prefetch the code splitted page. Setting 'no-prefetch' will disabled this feature for the specific link
link-attrs
ObjectAdditional attributes to place on the nested link element
link-classes
String or Object or ArraynullCSS class (or classes) to place on the nested link element

<b-nav-item> supports generating <router-link> or <nuxt-link> component (if using Nuxt.js). For more details on the router link (or nuxt link) specific props, see the Router support reference section.

<b-nav-text>

Functional component
View source

<b-nav-form>

Functional component
View source

Properties

PropertyTypeDefaultDescription
id
StringUsed to set the 'id' attribute on the rendered content, and used as the base to generate any additional element IDs as needed
novalidate
BooleanfalseWhen set, disables browser native HTML5 validation on controls in the form
validated
BooleanfalseWhen set, adds the Bootstrap class 'was-validated' on the form, triggering the native browser validation states
form-class
String or Array or Object

Events

EventArgumentsDescription
submit
  1. event - Native submit event.
Emitted when the form is being submitted

<b-nav-item-dropdown>

View source

Component aliases

<b-nav-item-dropdown> can also be used via the following aliases:

  • <b-nav-item-dd>
  • <b-nav-dropdown>
  • <b-nav-dd>

Note: component aliases are only available when importing all of BootstrapVue or using the component group plugin.

Properties

Property (Click to sort Ascending)TypeDefaultDescription
id
StringUsed to set the 'id' attribute on the rendered content, and used as the base to generate any additional element IDs as needed
disabled
BooleanfalseWhen set to 'true', disables the component's functionality and places it in a disabled state
dropup
BooleanfalseWhen set, positions the menu on the top of the button
dropright
BooleanfalseWhen set, positions the menu to the right of the button
dropleft
BooleanfalseWhen set, positions the menu to the left of the button
right
BooleanfalseAlign the right edge of the menu with the right of the button
offset
Number or String0
no-flip
BooleanfalsePrevent the menu from auto flipping positions
popper-opts
AnyAdditional configuration to pass to Popper.js
boundary
v2.4.0+ 		String or Object'scrollParent'The boundary constraint of the menu: 'scrollParent', 'window', 'viewport', or a reference to an HTMLElement. Has no effect when dropdown is inside a b-navbar
text
String''Text to place in the toggle button, or in the split button is split mode
html
StringHTML string to place in the toggle button, or in the split button is split mode. Use with caution
menu-class
String or Array or ObjectCSS class (or classes) to add to the menu container
toggle-class
String or Array or ObjectCSS class (or classes) to add to the toggle button
no-caret
BooleanfalseHide the caret indicator on the toggle button
role
String'menu'Sets the ARIA attribute 'role' to a specific value
lazy
BooleanfalseWhen set, will only mount the menu content into the DOM when the menu is open

Slots

Slot NameScopedDescription
button-content NoCan be used to implement custom text with icons and more styling.
default Optionally scoped default slot for dropdown menu content.

Events

EventArgumentsDescription
show
  1. bvEvt - BvEvent object. Call bvEvt.preventDefault() to cancel show.
Emitted just before dropdown is shown. Cancelable.
shown Emitted when dropdown is shown.
hide
  1. bvEvt - BvEvent object. Call bvEvt.preventDefault() to cancel hide.
Emitted just before dropdown is hidden. Cancelable.
hidden Emitted when dropdown is hidden.
toggle Emitted when toggle button is clicked.

Importing individual components

You can import individual components into your project via the following named exports:

ComponentNamed ExportImport Path
<b-nav>BNavbootstrap-vue
<b-nav-item>BNavItembootstrap-vue
<b-nav-text>BNavTextbootstrap-vue
<b-nav-form>BNavFormbootstrap-vue
<b-nav-item-dropdown>BNavItemDropdownbootstrap-vue

Example:

import { BNav } from 'bootstrap-vue'
Vue.component('b-nav', BNav)

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named ExportImport Path
NavPluginbootstrap-vue

This plugin also automatically includes the following plugins:

  • DropdownPlugin

Example:

import { NavPlugin } from 'bootstrap-vue'
Vue.use(NavPlugin)