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.
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
Link appearance
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.
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-navtabsfill><b-nav-itemactive>Active</b-nav-item><b-nav-item>Link</b-nav-item><b-nav-item>Link with a long name </b-nav-item><b-nav-itemdisabled>Disabled</b-nav-item></b-nav></div>
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-navtabsjustified><b-nav-itemactive>Active</b-nav-item><b-nav-item>Link</b-nav-item><b-nav-item>Link with a long name </b-nav-item><b-nav-itemdisabled>Disabled</b-nav-item></b-nav></div>
Alignment
To align your <b-nav-item> components, use the align prop. Available values are left, center and right.
<div><b-navtabsalign="center"><b-nav-itemactive>Active</b-nav-item><b-nav-item>Link</b-nav-item><b-nav-item>Link with a long name </b-nav-item><b-nav-itemdisabled>Disabled</b-nav-item></b-nav></div>
Vertical variation
By default <b-nav> appear on a horizontal line. Stack your navigation by setting the vertical prop.
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 render HTML similar to:
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.
Dropdown placement
Use the dropdown props right, dropup, dropright, dropleft, no-flip, and offset to control the positioning of <b-nav-item-dropdown>.
Note that the toggle button is actually rendered as a link <a> tag with role="button" for styling purposes, and typically has the href set to # unless an ID is provided via the id prop.
The toggle will prevent scroll-top-top behaviour (via JavaScript) when clicking the toggle link. In some cases when using SSR, and the user clicks the toggle button before Vue has had a chance to hydrate the component, the page will scroll to top. In these cases, simply providing a unique ID via the id prop will prevent the unwanted scroll-to-top behaviour.
Nav text content
Use the <b-nav-text> child component to place plain text content into the nav:
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:
With supporting text below as a natural lead-in to additional content.
<div><b-cardtitle="Card Title"no-body><b-card-headerheader-tag="nav"><b-navcard-headertabs><b-nav-itemactive>Active</b-nav-item><b-nav-item>Inactive</b-nav-item><b-nav-itemdisabled>Disabled</b-nav-item></b-nav></b-card-header><b-card-bodyclass="text-center"><b-card-text>
With supporting text below as a natural lead-in to additional content.
</b-card-text><b-buttonvariant="primary">Go somewhere</b-button></b-card-body></b-card></div>
Pill style:
With supporting text below as a natural lead-in to additional content.
<div><b-cardtitle="Card Title"no-body><b-card-headerheader-tag="nav"><b-navcard-headerpills><b-nav-itemactive>Active</b-nav-item><b-nav-item>Inactive</b-nav-item><b-nav-itemdisabled>Disabled</b-nav-item></b-nav></b-card-header><b-card-bodyclass="text-center"><b-card-text>
With supporting text below as a natural lead-in to additional content.
</b-card-text><b-buttonvariant="primary">Go somewhere</b-button></b-card-body></b-card></div>
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.
With supporting text below as a natural lead-in to additional content.
<div><b-cardtitle="Card Title"no-body><b-card-headerheader-tag="nav"><b-nav><b-nav-itemactive>Active</b-nav-item><b-nav-item>Inactive</b-nav-item><b-nav-itemdisabled>Disabled</b-nav-item></b-nav></b-card-header><b-card-bodyclass="text-center"><b-card-text>
With supporting text below as a natural lead-in to additional content.
</b-card-text><b-buttonvariant="primary">Go somewhere</b-button></b-card-body></b-card></div>
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-cardtitle="Card Title"no-body><b-card-headerheader-tag="nav"><b-navcard-headertabs><!-- <b-nav-item>'s with child routes. Note the trailing slash on the first <b-nav-item> --><b-nav-itemto="/some/route/"exactexact-active-class="active">Active</b-nav-item><b-nav-itemto="/some/route/foo"exactexact-active-class="active">Foo</b-nav-item><b-nav-itemto="/some/route/bar"exactexact-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.
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-item-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>
When set to `true`, places the component in the active state with active styling
active-class
String
<router-link> prop: Configure the active CSS class applied when the link is active. Typically you will want to set this to class name 'active'
append
Boolean
false
<router-link> prop: Setting append prop always appends the relative path to the current path
disabled
Boolean
false
When set to `true`, disables the component's functionality and places it in a disabled state
exact
Boolean
false
<router-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
String
<router-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'
exact-path
Boolean
false
<router-link> prop: Allows matching only using the path section of the url, effectively ignoring the query and the hash sections
exact-path-active-class
String
<router-link> prop: Configure the active CSS class applied when the link is active with exact path match. Typically you will want to set this to class name 'active'
href
String
<b-link> prop: Denotes the target URL of the link for standard a links
link-attrs
Object
{}
Additional attributes to place on the nested link element
link-classes
Array or Object or String
CSS class (or classes) to place on the nested link element
no-prefetch
Boolean
false
<nuxt-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
prefetch v2.15.0+
Boolean
null
<nuxt-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 `prefetch` to `true` or `false` will overwrite the default value of `router.prefetchLinks`
rel
String
null
<b-link> prop: Sets the `rel` attribute on the rendered link
replace
Boolean
false
<router-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
router-component-name v2.15.0+
String
<b-link> prop: BootstrapVue auto detects between `<router-link>` and `<nuxt-link>`. In cases where you want to use a 3rd party link component based on `<router-link>`, set this prop to the component name. e.g. set it to 'g-link' if you are using Gridsome (note only `<router-link>` specific props are passed to the component)
target
String
'_self'
<b-link> prop: Sets the `target` attribute on the rendered link
to
Object or String
<router-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
<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.
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>`
disabled
Boolean
false
When set to `true`, disables the component's functionality and places it in a disabled state
dropleft
Boolean
false
When set, positions the menu to the left of the button
dropright
Boolean
false
When set, positions the menu to the right of the button
dropup
Boolean
false
When set, positions the menu on the top of the button
html Use with caution
String
HTML string to place in the toggle element (link)
id
String
Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
lazy
Boolean
false
When set, will only mount the menu content into the DOM when the menu is open
menu-class
Array or Object or String
CSS class (or classes) to add to the menu container
no-caret
Boolean
false
Hide the caret indicator on the toggle element (link)
no-flip
Boolean
false
Prevent the menu from auto flipping positions
offset
Number or String
0
popper-opts
Object
{}
Additional configuration to pass to Popper.js
right
Boolean
false
Align the right edge of the menu with the right of the button
role
String
'menu'
Sets the ARIA attribute `role` to a specific value
text
String
Text to place in the toggle element (link)
toggle-class
Array or Object or String
CSS class (or classes) to add to the toggle element (link)
Caution: Props that support HTML strings
(*-html) can be vulnerable to
Cross Site Scripting (XSS) attacks
when passed raw user supplied values. You must properly
sanitize
the user input first!
Slots
Name
Scoped
Description
button-content
No
Can be used to implement custom text with icons and more styling
default
Optionally scoped default slot for dropdown menu content
Events
Event
Arguments
Description
hidden
Emitted when dropdown is hidden
hide
bvEvent -
BvEvent object. Call bvEvent.preventDefault() to cancel hide
Emitted just before dropdown is hidden. Cancelable
show
bvEvent -
BvEvent object. Call bvEvent.preventDefault() to cancel show
Emitted just before dropdown is shown. Cancelable
shown
Emitted when dropdown is shown
toggle
Emitted when toggle button is clicked
Importing individual components
You can import individual components into your project via the following named
exports: