QTabs and QNav are the main navigation primitives in the DSY component library. Use them to organize content into sections (Tabs) or to render a flat list of links (Nav).

When to Use ​

  • When content is naturally divided into distinct sections that users navigate between without leaving the page
  • For page-level or panel-level navigation where a tab-strip (QTabs) or flat link list (QNav) keeps the layout compact
  • For secondary navigation within a view — e.g. switching between Overview, Details, and History tabs

When Not to Use ​

  • For primary top-level navigation — use QNavbar instead
  • When sections have very different depths or require their own URL — use page routing instead
  • For a single section with no alternatives — remove the tab bar entirely

Component Anatomy ​

  • QTabs — a tab strip bound to a numeric v-model index; renders an ordered list of tab labels and a content area controlled by named slots
  • QNav — a flat link list rendered as a <ul> of <li> anchor elements; supports dropdown children, icons, and vertical layout
  • Tab item — a single entry in the list array; can carry a title, key, disabled, iconStart, and iconEnd
  • Tab content — keyed slots matching tab.key (or the numeric index) that hold the content rendered when a tab is active

A horizontal (or vertical) list of links. Wraps Bootstrap's nav component and adds icon support and dropdown handling.

Pass vertical to render the nav as a column. Useful for sidebar navigation.

Tabs ​

Default tab-style navigation. The underline indicates the active tab. Pass a list array of TabItem objects and bind v-model to the active tab index.

Pills ​

Use pill for a button-style navigation where the active item has a filled primary background. Suitable for compact filter bars and secondary navigation within a page.

Vertical ​

Use vertical to render the nav column on the left side of the content. A border-right separator and a left-border active indicator are applied automatically. Avoid combining with fill in vertical mode.

Fill ​

Use fill to make all tab items occupy equal width in the nav bar. Only meaningful in horizontal mode.

Custom Tab Title ​

Use the tab-title slot to override the default title rendering. The tab object is available in the slot scope.

Tabs End Content ​

Use the tabs-end slot to inject content at the end of the tab bar — for example a button or a badge.

Props ​

PropTypeDefaultDescription
v-modelNumber—Index of the active tab (required)
listTabItem[][{ title: "" }]Array of tab definitions
pillBooleanfalseRenders pills style instead of underline tabs
fillBooleanfalseMakes all items equal width. Use only in horizontal mode
verticalBooleanfalseRenders the nav column on the left
smallBooleanfalseReduces the size of the nav items
navClassStringnullExtra class applied to the <ul> nav element
navItemClassStringnullExtra class applied to each <li> nav item
navWrapperClassStringnullExtra class applied to the nav wrapper
contentClassStringnullExtra class applied to the .tab-content element
scrollToOptionsScrollToOptionsundefinedIf set, the tab content scrolls to the given position on tab change

TabItem model ​

ts
interface TabItem<T = unknown> {
  title: string
  key?: string          // used as named slot for tab content
  disabled?: boolean
  iconStart?: string    // Bootstrap Icons class, e.g. "bi-house"
  iconStartClass?: string
  iconEnd?: string
  iconEndClass?: string
  dataTab?: T           // arbitrary payload passed back in slot scope
}

Slots ​

SlotScopeDescription
tab-title{ tab: TabItem }Custom title renderer for every tab
[tab.key | tabIndex]{ tab: TabItem }Content area for each tab, keyed by tab.key or numeric index
tabs-end—Content rendered at the end of the tab bar

Accessibility ​

  • The tab list renders with role="tablist"; each tab label has role="tab" and the active tab has aria-selected="true"
  • Disabled tabs have aria-disabled="true" and do not receive focus
  • Keyboard navigation follows the ARIA tabs pattern: Arrow Left / Right moves between tabs, Home jumps to the first tab, End to the last
  • Each tab panel has role="tabpanel" and is associated with its label via aria-labelledby
  • For QNav, ensure each link has a descriptive label or visible text — icon-only links need aria-label