Nav
Navigation available in Bootstrap share general markup and styles, from the base <BNav> class to the active and disabled states. Swap modifier props to switch between each style.
Overview
The base <BNav> 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.
<BNav> supports the following child components:
<BNavItem>for actionable links (or router-links)<BNavItemDropdown>for dropdowns<BNavText>for plain text content<BNavForm>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.
Pill style
Use the pill style by setting the pills prop.
Small
Make the nav smaller by setting the small prop.
Fill and justify
Force your <BNav> content to extend the full available width.
Fill
To proportionately fill all available space with your <BNavItem> components, set the fill prop. Notice that all horizontal space is occupied, but not every nav item has the same width.
Justified
For equal-width elements, set the justified prop instead. All horizontal space will be occupied by nav links, but unlike fill above, every <BNavItem> will be the same width.
Alignment
To align your <BNavItem> components, use the align prop. Available values are those from AlignmentJustifyContent: start, center, end, between, around, and evenly.
Vertical variation
By default <BNav> appear on a horizontal line. Stack your navigation by setting the vertical prop.
Dropdown support
Use <BNavItemDropdown> to place dropdown items within your nav.
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 <BDropdown> 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. |
show() | Can be used to show the dropdown menu. |
Lazy dropdown
By default, <BNavItemDropdown> 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 <BNavItemDropdown> to render the menu contents only when it is shown by setting the lazy prop to true.
Dropdown placement
Use the start, end, center, placement, no-flip, and offset to control the positioning of <BNavItemDropdown>.
Refer to the <BDropdown> positioning section for details on the effects and usage of these props.
Dropdown implementation note
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.
Dropdown Exposed Methods
<BNavItemDropdown> exposes the same methods as <BDropdown>, see the dropdown documentation for details.
Nav text content
Use the <BNavText> child component to place plain text content into the nav:
Nav inline forms
Use the <BNavForm> child component to place an inline form into the nav:
Refer to the <BForm> inline documentation for additional details on placing form controls.
Tabbed local content support
See the <BTabs> component for creating tabbable panes of local content (not suited for navigation).
Card integration
Use a <BNav> in a <BCard> header, by enabling the card-header prop on <BNav> and setting either the pills or tabs props:
Tabs style:
Pill style:
Plain style:
The card-header prop is only needed when you are applying tabs or pills style. Note that Bootstrap v5 SCSS does not have special styling for active state plain style nav items.
The card-header prop has no styling effect if the <BNav> is in vertical mode.
Using with Vue Router
Have your card <BNav> control vue router nested routes via <router-view> or <nuxt-child> components, to created tabbed content that changes with route URL:
INFO
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:
One can also use Vue Router named routes and/or route params instead of path based routes.
For more details see:
Component Reference
<BNav>
| Prop | Type | Default | Description |
|---|---|---|---|
| align | AlignmentJustifyContent | undefined | Aligns the nav items to any value of AlignmentJustifyContent |
| card-header | boolean | false | Indicates the nav is placed inside a card header |
| fill | boolean | false | Fills all horizontal space with nav items proportionally, with varying widths |
| justified | boolean | false | Fills all horizontal space with nav items, each having equal width |
| pills | boolean | false | Styles nav items as pill buttons |
| small | boolean | false | Reduces the nav size |
| tabs | boolean | false | Styles nav items as tabs |
| tag | string | 'ul' | Specify the HTML tag to render instead of the default tag |
| underline | boolean | false | Underlines the active nav item |
| vertical | boolean | false | Stacks nav items vertically |
| Name | Scope | Description |
|---|---|---|
| default | Content for the nav |
<BNavForm>
| Prop | Type | Default | Description |
|---|---|---|---|
| floating | boolean | false | When set, renders a single control form with a floating label. This only works for forms where the immediate children are a label and one of the supported controls. See above for details. |
| form-class | ClassValue | undefined | CSS class (or classes) to apply to the form element |
| id | string | undefined | Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed |
| novalidate | boolean | false | When set, disables browser native HTML5 validation on controls in the form |
| role | string | undefined | Sets the ARIA attribute `role` to a specific value |
| validated | boolean | false | When set, adds the Bootstrap class 'was-validated' on the form, triggering the native browser validation states |
| wrapper-attrs | Readonly<AttrsValue> | undefined | Attributes to be applied to the wrapper element |
| Event | Args | Description |
|---|---|---|
| submit | submit: Event - Native submit event | Emitted when the form is submitted |
| Name | Scope | Description |
|---|---|---|
| default | Content for the nav form |
<BNavItem>
| Prop | Type | Default | Description |
|---|---|---|---|
| link-attrs | Readonly<AttrsValue> | undefined | Additional attributes for the nested link element |
| link-class | ClassValue | undefined | CSS class (or classes) for the nested link element |
| Event | Args | Description |
|---|---|---|
| click | click: MouseEvent - Click event details | Emitted when a non-disabled nav item is clicked |
| Name | Scope | Description |
|---|---|---|
| after | Content placed after the nav item link (useful for nested navs) | |
| default | Content for the nav item |
<BNavItemDropdown>
.nav‑item.dropdown| Prop | Type | Default | Description |
|---|---|---|---|
| aria-label | string | undefined | Sets the value of `aria-label` attribute on the rendered element |
| auto-close | boolean | 'inside' | 'outside' | true | Controls the automatic closing of the dropdown when clicking. See above for details. |
| boundary | Boundary | RootBoundary | 'clippingAncestors' | The boundary constraint of dropdown: any value of floating-us's Boundary or RootBoundary type. See above for details. |
| boundary-padding | Padding | undefined | The virtual padding around the boundary to check for overflow |
| disabled | boolean | false | When set to `true`, disables the component's functionality and places it in a disabled state |
| floating-middleware | Middleware[] | undefined | Directly set the floating-ui middleware behavior. See above for details. |
| icon | boolean | false | When set, styles an icon at the beginning or end of the button text |
| id | string | undefined | Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed |
| initial-animation | boolean | false | When set, enables the initial animation on mount |
| is-nav | boolean | false | Indicates the dropdown is a nav dropdown |
| lazy | boolean | false | When set, the content will not be mounted until opened |
| menu-class | ClassValue | undefined | CSS class (or classes) to add to the menu container |
| model-value | boolean | false | Controls the visibility of the component |
| no-animation | boolean | false | When set, disables the animation |
| no-caret | boolean | false | Hide the caret indicator on the toggle button |
| no-fade | boolean | false | Alias for `noAnimation` |
| no-flip | boolean | false | Prevent the menu from auto flipping positions |
| no-shift | boolean | false | Prevent the menu from automatically shifting positions |
| no-size | boolean | false | Prevent the menu from automatically resizing |
| no-wrapper | boolean | false | Do not render the dropdown wrapper element |
| offset | number | string | {mainAxis?: number; crossAxis?: number; alignmentAxis?: number | null | 0 | Specify the number of pixels to shift the menu by. See above for details. |
| placement | Placement | 'bottom-start' | Placement of a floating element |
| role | string | 'menu' | Sets the ARIA attribute `role` to a specific value |
| show | boolean | false | When set, and prop 'visible' is false on mount, will animate from closed to open on initial mount. Mainly to help with template show. Use model-value for reactive show/hide |
| size | Size | 'md' | Set the size of the component's appearance. 'sm', 'md' (default), or 'lg' |
| split | boolean | false | When set, renders a split button dropdown |
| split-button-type | ButtonType | 'button' | Value to place in the 'type' attribute on the split button: 'button', 'submit', 'reset' |
| split-class | ClassValue | undefined | CSS class (or classes) to add to the split button |
| split-disabled | boolean | undefined | When set, the split button is disabled |
| split-href | string | undefined | Denotes the target URL of the link for the split button |
| split-to | RouteLocationRaw | undefined | Denotes the target route of the split button. 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 |
| split-variant | ButtonVariant | null | undefined | Applies one of the Bootstrap theme color variants to the split button. Defaults to the 'variant' prop value |
| strategy | Strategy | 'absolute' | The strategy used to determine when to hide the dropdown. See above for details. |
| teleport-disabled | boolean | false | Renders the dropdown in the exact place it was defined |
| teleport-to | string | RendererElement | null | undefined | undefined | Overrides the default teleport location |
| text | string | undefined | Text to place in the toggle button, or in the split button is split mode |
| toggle-class | ClassValue | undefined | CSS class (or classes) to add to the toggle button |
| toggle-text | string | 'Toggle dropdown' | ARIA label (visually-hidden) to set on the toggle when in split mode. Overriden by the slot of the same name |
| trans-props | TransitionProps | undefined | Transition properties |
| unmount-lazy | boolean | false | When set and `lazy` is true, the content will be unmounted when closed |
| variant | ColorVariant | null | 'secondary' | Applies one of the Bootstrap theme color variants to the component. When implemented `bg-variant` and `text-variant` will take precedence |
| visible | boolean | false | When 'true', open without animation |
| wrapper-class | ClassValue | undefined | CSS class (or classes) to add to the wrapper element |
| Event | Args | Description |
|---|---|---|
| cancel | value: BvTriggerableEvent | Emitted when a cancel action is triggered. |
| hidden | value: BvTriggerableEvent | Always emits after the component is hidden |
| hide | value: BvTriggerableEvent - Call value.preventDefault() to cancel hide | Always emits just before the component has hidden. Cancelable (as long as component wasn't forcibly hidden) |
| hide-prevented | value: BvTriggerableEvent | Emitted when the component tried to close, but was prevented from closing. This occurs when preventDefault() is called on the event, the user clicks escape and no-close-onbackdrop is set to true, or the user clicks on the backdrop and no-close-onbackdrop is set to true. |
| ok | value: BvTriggerableEvent | Emitted when an ok action is triggered. |
| show | value: BvTriggerableEvent - Call value.preventDefault() to cancel show | Always emits just before the component is shown. Cancelable |
| show-prevented | value: BvTriggerableEvent | Emitted when the component tried to open, but was prevented from opening. This occurs when preventDefault() is called on the event |
| shown | value: BvTriggerableEvent | Always emits just after component is shown. |
| split-click | event: MouseEvent - Native click event object | Emitted when split button is clicked in split mode |
| toggle | Emitted when toggle button is clicked | |
| toggle-prevented | value: BvTriggerableEvent | Emitted when the component tried to toggle, but was prevented from doing so. This occurs when preventDefault() is called on the event, the user clicks escape and no-close-onbackdrop is set to true, or the user clicks on the backdrop and no-close-onbackdrop is set to true. |
| Name | Scope | Description |
|---|---|---|
| button-content | Can be used to implement custom text with icons and more styling | |
| default | hide: () => void - Can be used to close the dropdownshow: () => void - Can be used to open the dropdown | Optionally scoped default slot for dropdown menu content |
| toggle-text | ARIA label (visually-hidden) to set on the toggle when in split mode. Overrides the toggle-text prop |
<BNavText>
.navbar‑text| Prop | Type | Default | Description |
|---|---|---|---|
| text | string | undefined | Plain text to display in the nav |
| Name | Scope | Description |
|---|---|---|
| default | Content to display in the nav |