Navs

- Documentation + Documentation

diff --git a/site/src/content/docs/components/alert.mdx b/site/src/content/docs/components/alert.mdx index edfe19f75d..7657979b56 100644 --- a/site/src/content/docs/components/alert.mdx +++ b/site/src/content/docs/components/alert.mdx @@ -120,6 +120,14 @@ For the sole purpose of dismissing an alert, it isnât necessary to initialize See the [triggers](#triggers) section for more details. +### Via data attributes + + +| Attribute | Description | +| --- | --- | +| `data-bs-dismiss="alert"` | On a close control, dismisses (and removes) the alert when activated. | + + ### Triggers diff --git a/site/src/content/docs/components/button-group.mdx b/site/src/content/docs/components/button-group.mdx index 44cb18257b..c90584b121 100644 --- a/site/src/content/docs/components/button-group.mdx +++ b/site/src/content/docs/components/button-group.mdx @@ -18,7 +18,7 @@ Wrap a series of buttons in `.btn-group`. Button groups require an appropriate `role` attribute and explicit label to ensure assistive technologies like screen readers identify buttons as grouped and announce them. Use `role="group"` for button groups or `role="toolbar"` for button toolbars. Then use `aria-label` or `aria-labelledby` to label them. -These classes can also be added to groups of links, as an alternative to the [`.nav` navigation components]([[docsref:/components/navs-tabs]]). +These classes can also be added to groups of links, as an alternative to the [`.nav` navigation components]([[docsref:/components/nav]]). Active link diff --git a/site/src/content/docs/components/buttons.mdx b/site/src/content/docs/components/buttons.mdx index 5248549755..bfc57eee8e 100644 --- a/site/src/content/docs/components/buttons.mdx +++ b/site/src/content/docs/components/buttons.mdx @@ -248,6 +248,14 @@ Add `data-bs-toggle="button"` to toggle a buttonâs `active` state. If youâre Active toggle link Disabled toggle link`} /> +### Via data attributes + + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="button"` | Toggles the buttonâs active (`pressed`) state via the Button plugin. | + + ### Methods You can create a button instance with the button constructor, for example: diff --git a/site/src/content/docs/components/card.mdx b/site/src/content/docs/components/card.mdx index 424a7bfbbf..97ffba3790 100644 --- a/site/src/content/docs/components/card.mdx +++ b/site/src/content/docs/components/card.mdx @@ -257,7 +257,7 @@ Use custom CSS in your stylesheets or as inline styles to set a width. ## Navigation -Add some navigation to a cardâs header (or block) with Bootstrapâs [nav components]([[docsref:/components/navs-tabs]]). +Add some navigation to a cardâs header (or block) with Bootstrapâs [nav components]([[docsref:/components/nav]]).

diff --git a/site/src/content/docs/components/carousel.mdx b/site/src/content/docs/components/carousel.mdx index b183875ec6..0a1dea2a12 100644 --- a/site/src/content/docs/components/carousel.mdx +++ b/site/src/content/docs/components/carousel.mdx @@ -337,6 +337,15 @@ Tokens for the [dark carousel](#dark-carousel): Use data attributes to easily control the position of the carousel. `data-bs-slide` accepts the keywords `prev` or `next`, which alters the slide position relative to its current position. Alternatively, use `data-bs-slide-to` to pass a raw slide index to the carousel `data-bs-slide-to="2"`, which shifts the slide position to a particular index beginning with `0`. + +| Attribute | Description | +| --- | --- | +| `data-bs-ride` | Starts autoplay after the first manual cycle (`true`) or on load (`carousel`). | +| `data-bs-slide` | `prev` or `next` to move the carousel relative to the current slide. | +| `data-bs-slide-to` | Zero-based index of the slide to show. | +| `data-bs-interval` | Autoplay interval in milliseconds between slides. | + + ### Via JavaScript Call carousel manually with: diff --git a/site/src/content/docs/components/collapse.mdx b/site/src/content/docs/components/collapse.mdx index 3c6ff9291f..e164049585 100644 --- a/site/src/content/docs/components/collapse.mdx +++ b/site/src/content/docs/components/collapse.mdx @@ -118,6 +118,14 @@ Just add `data-bs-toggle="collapse"` and a `data-bs-target` to the element to au To add accordion-like group management to a collapsible area, add the data attribute `data-bs-parent="#selector"`. Refer to the [accordion page]([[docsref:/components/accordion]]) for more information. + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="collapse"` | Initializes the collapse plugin on the trigger element. | +| `data-bs-target` | CSS selector for the element(s) to expand and collapse. | +| `data-bs-parent` | When set on the collapsible element, closes sibling collapses under the same parent (accordion behavior). | + + ### Via JavaScript Enable manually with: diff --git a/site/src/content/docs/components/dialog.mdx b/site/src/content/docs/components/dialog.mdx index 9fe9133ac5..6f8f11dff9 100644 --- a/site/src/content/docs/components/dialog.mdx +++ b/site/src/content/docs/components/dialog.mdx @@ -459,6 +459,14 @@ Dialog sizes are defined in the `$dialog-sizes` Sass map. Each size specifies th Toggle a dialog without writing JavaScript. Set `data-bs-toggle="dialog"` on a controller element, like a button, along with a `data-bs-target="#foo"` to target a specific dialog to toggle. + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="dialog"` | Opens or toggles the dialog from the trigger element. | +| `data-bs-target` | CSS selector for the dialog element to show or hide. | +| `data-bs-dismiss="dialog"` | On a control inside the dialog, closes the dialog when activated. | + + ```html + + Disabled + `} /> + +## Tab JavaScript plugin + +Use the [tab JavaScript plugin]([[docsref:/components/tab#javascript-behavior]]) to create tabbable regions. + +## Available styles + +Change the style of `.nav`s component with modifiers and utilities. Mix and match as needed, or build your own. + +### Tabs + +Takes the basic nav from above and adds the `.nav-tabs` class to generate a tabbed interface. + + +

+ Active +

+ Link +

+ Disabled +

+ `} /> + +### Pills + +Take that same HTML, but use `.nav-pills` instead for a more themed appearance. + + +

+ Active +

+ Link +

+ Disabled +

+ `} /> + +### Underline + +Take that same HTML, but use `.nav-underline` instead: + + +

+ Active +

+ Link +

+ Disabled +

+ `} /> + +## Alignment + +Change the alignment of your nav with [flexbox utilities]([[docsref:/utilities/flex]]). By default, navs are horizontal and left-aligned, but you can easily modify them to center or right-aligned, and even stacked vertically. + +### Horizontal + +Centered with `.justify-content-center`: + + +

+ Active +

+ Link +

+ Disabled +

+ `} /> + +Right-aligned with `.justify-content-end`: + + +

+ Active +

+ Link +

+ Disabled +

+ `} /> + +### 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`). + + +

+ Active +

+ Link +

+ Disabled +

+ `} /> + +As always, vertical navigation is possible without `

+ Active + Link + Link + Disabled + `} /> + +### Fill and justify + +Force your `.nav`âs contents to extend the full available width with one of two modifier classes. To proportionately fill all available space with your `.nav-item`s, use `.nav-fill`. Notice that all horizontal space is occupied, but not every nav item has the same width. + + +

+ Active +

+ Much longer nav link +

+ Link +

+ Disabled +

`} /> + +When using a ``} /> + +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. + + +

+ Active +

+ Much longer nav link +

+ Link +

+ Disabled +

+ `} /> + +Similar to the `.nav-fill` example using a ``} /> + +## Working with flex utilities + +If you need responsive nav variations, consider using a series of [flexbox utilities]([[docsref:/utilities/flex]]). While more verbose, these utilities offer greater customization across responsive breakpoints. In the example below, our nav will be stacked on the lowest breakpoint, then adapt to a horizontal layout that fills the available width starting from the small breakpoint. + + + Active + Longer nav link + Link + Disabled + `} /> + +## 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 `

` element around the whole navigation. Do not add the role to the `

+ Active +

+ Menu + +

+ Link +

+ Disabled +

`} /> + +### Pills with menus + + +

+ Active +

+ Menu + +

+ Link +

+ Disabled +

`} /> + +## CSS + +### Variables + + + +On the `.nav` base class: + + + +On the `.nav-tabs` modifier class: + + + +On the `.nav-pills` modifier class: + + + +On the `.nav-underline` modifier class: + + diff --git a/site/src/content/docs/components/navs-tabs.mdx b/site/src/content/docs/components/navs-tabs.mdx deleted file mode 100644 index f613d3e8af..0000000000 --- a/site/src/content/docs/components/navs-tabs.mdx +++ /dev/null @@ -1,669 +0,0 @@ ---- -title: Navs and tabs -description: Add lists of links to your pages with Bootstrapâs nav components and JavaScript-powered tabs. -aliases: "/docs/[[config:docs_version]]/components/navs/" -toc: true ---- - -## Base nav - -Navigation available in Bootstrap share general markup and styles, from the base `.nav` class to the active and disabled states. Swap modifier classes to switch between each style. - -The base `.nav` component is built with flexbox and provide 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. - - -To convey the active state to assistive technologies, use the `aria-current` attribute â using the `page` value for current page, or `true` for the current item in a set. - - - -

- Active -

- Link -

- Disabled -

- `} /> - -Classes are used throughout, so your markup can be super flexible. Use `

Disabled

- Active -

- Link -

- Disabled -

`} /> - -### Pills - -Take that same HTML, but use `.nav-pills` instead for a more themed appearance. - - -

- Active -

- Link -

- Disabled -

- `} /> - -### Underline - -Take that same HTML, but use `.nav-underline` instead: - - -

- Active -

- Link -

- Disabled -

- `} /> - -## Alignment - -Change the alignment of your nav with [flexbox utilities]([[docsref:/utilities/flex]]). By default, navs are horizontal and left-aligned, but you can easily modify them to center or right-aligned, and even stacked vertically. - -### Horizontal - -Centered with `.justify-content-center`: - - -

- Active -

- Link -

- Disabled -

- `} /> - -Right-aligned with `.justify-content-end`: - - -

- Active -

- Link -

- Disabled -

- `} /> - -### 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`). - - -

- Active -

- Link -

- Disabled -

- `} /> - -As always, vertical navigation is possible without `

- Active - Link - Link - Disabled - `} /> - -### Fill and justify - -Force your `.nav`âs contents to extend the full available width with one of two modifier classes. To proportionately fill all available space with your `.nav-item`s, use `.nav-fill`. Notice that all horizontal space is occupied, but not every nav item has the same width. - - -

- Active -

- Much longer nav link -

- Link -

- Disabled -

`} /> - -When using a ``} /> - -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. - - -

- Active -

- Much longer nav link -

- Link -

- Disabled -

- `} /> - -Similar to the `.nav-fill` example using a ``} /> - -## Working with flex utilities - -If you need responsive nav variations, consider using a series of [flexbox utilities]([[docsref:/utilities/flex]]). While more verbose, these utilities offer greater customization across responsive breakpoints. In the example below, our nav will be stacked on the lowest breakpoint, then adapt to a horizontal layout that fills the available width starting from the small breakpoint. - - - Active - Longer nav link - Link - Disabled - `} /> - -## 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 `

` element around the whole navigation. Do not add the role to the `

- Active -

- Menu - -

- Link -

- Disabled -

`} /> - -### Pills with menus - - -

- Active -

- Menu - -

- Link -

- Disabled -

`} /> - -## CSS - -### Variables - - - -On the `.nav` base class: - - - -On the `.nav-tabs` modifier class: - - - -On the `.nav-pills` modifier class: - - - -On the `.nav-underline` modifier class: - - - -## JavaScript behavior - -Use the tab JavaScript pluginâinclude it individually or through the compiled `bootstrap.js` fileâto extend our navigational tabs and pills to create tabbable panes of local content. - - -

- -

This is some placeholder content the Home tabâs associated content. Clicking another tab will toggle the visibility of this one for the next. The tab JavaScript swaps classes to control the content visibility and styling. You can use it with tabs, pills, and any other .nav-powered navigation.

This is some placeholder content the Profile tabâs associated content. Clicking another tab will toggle the visibility of this one for the next. The tab JavaScript swaps classes to control the content visibility and styling. You can use it with tabs, pills, and any other .nav-powered navigation.

This is some placeholder content the Contact tabâs associated content. Clicking another tab will toggle the visibility of this one for the next. The tab JavaScript swaps classes to control the content visibility and styling. You can use it with tabs, pills, and any other .nav-powered navigation.

This is some placeholder content the Disabled tabâs associated content.

-`} /> - -```html -

...

-``` - -To help fit your needs, this works with `

`, you shouldnât add `role="tablist"` directly to it, as this would override the elementâs native role as a navigation landmark. Instead, switch to an alternative element (in the example below, a simple `

`) and wrap the ` -

This is some placeholder content the Disabled tabâs associated content.

-`} /> - -```html - -

...

-``` - -The tabs plugin also works with pills. - - -

- -

This is some placeholder content the Disabled tabâs associated content.

-`} /> - -```html -

...

-``` - -And with vertical pills. Ideally, for vertical tabs, you should also add `aria-orientation="vertical"` to the tab list container. - - -

- - - - - -

This is some placeholder content the Disabled tabâs associated content.

This is some placeholder content the Messages tabâs associated content. Clicking another tab will toggle the visibility of this one for the next. The tab JavaScript swaps classes to control the content visibility and styling. You can use it with tabs, pills, and any other .nav-powered navigation.

This is some placeholder content the Settings tabâs associated content. Clicking another tab will toggle the visibility of this one for the next. The tab JavaScript swaps classes to control the content visibility and styling. You can use it with tabs, pills, and any other .nav-powered navigation.

-`} /> - -```html -

- - - - - -

...

-``` - -### Accessibility - -Dynamic tabbed interfaces, as described in the [ARIA Authoring Practices Guide tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/), 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 ` - -

- -

- - - -

...

-``` - -### Via JavaScript - -Enable tabbable tabs via JavaScript (each tab needs to be activated individually): - -```js -const triggerTabList = document.querySelectorAll('#myTab button') -triggerTabList.forEach(triggerEl => { - const tabTrigger = new bootstrap.Tab(triggerEl) - - triggerEl.addEventListener('click', event => { - event.preventDefault() - tabTrigger.show() - }) -}) -``` - -You can activate individual tabs in several ways: - -```js -const triggerEl = document.querySelector('#myTab button[data-bs-target="#profile"]') -bootstrap.Tab.getInstance(triggerEl).show() // Select tab by name - -const triggerFirstTabEl = document.querySelector('#myTab li:first-child button') -bootstrap.Tab.getInstance(triggerFirstTabEl).show() // Select first tab -``` - -### Fade effect - -To make tabs fade in, add `.fade` to each `.tab-pane`. The first tab pane must also have `.show` to make the initial content visible. - -```html -

...

-``` - -### Methods - - - -Activates your content as a tab element. - -You can create a tab instance with the constructor, for example: - -```js -const bsTab = new bootstrap.Tab('#myTab') -``` - - -| Method | Description | -| --- | --- | -| `dispose` | Destroys an elementâs tab. | -| `getInstance` | Static method which allows you to get the tab instance associated with a DOM element, you can use it like this: `bootstrap.Tab.getInstance(element)`. | -| `getOrCreateInstance` | Static method which returns a tab instance associated to a DOM element or create a new one in case it wasnât initialized. You can use it like this: `bootstrap.Tab.getOrCreateInstance(element)`. | -| `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.bs.tab` event occurs). | - - -### Events - -When showing a new tab, the events fire in the following order: - -1. `hide.bs.tab` (on the current active tab) -2. `show.bs.tab` (on the to-be-shown tab) -3. `hidden.bs.tab` (on the previous active tab, the same one as for the `hide.bs.tab` event) -4. `shown.bs.tab` (on the newly-active just-shown tab, the same one as for the `show.bs.tab` event) - -If no tab was already active, then the `hide.bs.tab` and `hidden.bs.tab` events will not be fired. - - -| Event type | Description | -| --- | --- | -| `hide.bs.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.bs.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. | -| `show.bs.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.bs.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. | - - -```js -const tabEl = document.querySelector('button[data-bs-toggle="tab"]') -tabEl.addEventListener('shown.bs.tab', event => { - event.target // newly activated tab - event.relatedTarget // previous active tab -}) -``` diff --git a/site/src/content/docs/components/offcanvas.mdx b/site/src/content/docs/components/offcanvas.mdx index 2625dc0704..7a5d4f6182 100644 --- a/site/src/content/docs/components/offcanvas.mdx +++ b/site/src/content/docs/components/offcanvas.mdx @@ -290,6 +290,14 @@ Add a dismiss button with the `data-bs-dismiss="offcanvas"` attribute, which tri ### Via data attributes + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="offcanvas"` | Initializes offcanvas behavior on the trigger element. | +| `data-bs-target` | CSS selector for the `.offcanvas` element to open (or use `href` on a link). | +| `data-bs-dismiss="offcanvas"` | On a dismiss control, closes the offcanvas when activated. | + + #### Toggle Add `data-bs-toggle="offcanvas"` and a `data-bs-target` or `href` to the element to automatically assign control of one offcanvas element. The `data-bs-target` attribute accepts a CSS selector to apply the offcanvas to. Be sure to add the class `offcanvas` to the offcanvas element. If youâd like it to default open, add the additional class `show`. diff --git a/site/src/content/docs/components/popover.mdx b/site/src/content/docs/components/popover.mdx index 38dafd9720..7e2333a75f 100644 --- a/site/src/content/docs/components/popover.mdx +++ b/site/src/content/docs/components/popover.mdx @@ -198,6 +198,20 @@ Avoid adding an excessive amount of content in popovers with the `html` option. Popovers do not manage keyboard focus order, and their placement can be random in the DOM, so be careful when adding interactive elements (like forms or links), as it may lead to an illogical focus order or make the popover content itself completely unreachable for keyboard users. In cases where you must use these elements, consider using a dialog instead. +### Via data attributes + + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="popover"` | Initializes the popover on the trigger element. | +| `data-bs-title` | Title content shown in the popover header. | +| `data-bs-content` | Body content of the popover. | +| `data-bs-placement` | Where to place the popover relative to the trigger. | +| `data-bs-trigger` | How the popover opens (`click`, `hover`, `focus`, `manual`, or a combination). | +| `data-bs-custom-class` | Extra class names added to the popover for theming. | +| `data-bs-html` | When `true`, allows HTML in the title and content (use with care for untrusted input). | + + ### Dependencies The popover plugin extends the tooltip plugin, so it requires all tooltip dependencies plus its own: diff --git a/site/src/content/docs/components/scrollspy.mdx b/site/src/content/docs/components/scrollspy.mdx index 7f14327c0f..88f340d529 100644 --- a/site/src/content/docs/components/scrollspy.mdx +++ b/site/src/content/docs/components/scrollspy.mdx @@ -6,7 +6,7 @@ toc: true ## How it works -Scrollspy toggles the `.active` class on anchor (``) elements when the element with the `id` referenced by the anchorâs `href` is scrolled into view. Scrollspy is best used in conjunction with a Bootstrap [nav component]([[docsref:/components/navs-tabs]]) or [list group]([[docsref:/components/list-group]]), but it will also work with any anchor elements in the current page. Hereâs how it works. +Scrollspy toggles the `.active` class on anchor (``) elements when the element with the `id` referenced by the anchorâs `href` is scrolled into view. Scrollspy is best used in conjunction with a Bootstrap [nav component]([[docsref:/components/nav]]) or [list group]([[docsref:/components/list-group]]), but it will also work with any anchor elements in the current page. Hereâs how it works. - To start, scrollspy requires two things: a navigation, list group, or a simple set of links, plus a scrollable container. The scrollable container can be the `` or a custom element with a set `height` and `overflow-y: scroll`. @@ -344,6 +344,13 @@ document.querySelectorAll('#nav-tab>[data-bs-toggle="tab"]').forEach(el => { To easily add scrollspy behavior to your topbar navigation, add `data-bs-spy="scroll"` to the element you want to spy on (most typically this would be the ``). Then add the `data-bs-target` attribute with the `id` or class name of the parent element of any Bootstrap `.nav` component. + +| Attribute | Description | +| --- | --- | +| `data-bs-spy="scroll"` | Enables ScrollSpy on the scrollable element (often ``). | +| `data-bs-target` | CSS selector for the nav whose links match sections in the spied element. | + + ```html ... diff --git a/site/src/content/docs/components/tab.mdx b/site/src/content/docs/components/tab.mdx new file mode 100644 index 0000000000..5c9c83d263 --- /dev/null +++ b/site/src/content/docs/components/tab.mdx @@ -0,0 +1,301 @@ +--- +title: Tab +description: Create toggleable content panes using any of our navigation or list group components with this JavaScript plugin. +toc: true +--- + +The Tab plugin works with [nav components]([[docsref:/components/nav]]) such as `.nav-tabs` and `.nav-pills`, and with [list groups]([[docsref:/components/list-group#javascript-behavior]]). + +## Nav tab + +Add the required data attributes and `id` to your navigation to make it tabbable. Then, add the `tab-content` container with matching `id`s to each tab pane. + + +

+ +

This is some placeholder content the Home tabâs associated content.

This is some placeholder content the Profile tabâs associated content.

This is some placeholder content the Contact tabâs associated content.

This is some placeholder content the Disabled tabâs associated content.

`} /> + +## With buttons + +To help fit your needs, this works with `

`) and wrap the ` +

This is some placeholder content the Home tabâs associated content.

This is some placeholder content the Profile tabâs associated content.

This is some placeholder content the Contact tabâs associated content.

This is some placeholder content the Disabled tabâs associated content.

`} /> + +## Pills + +The tabs plugin also works with pills. + + +

+ +

This is some placeholder content the Home tabâs associated content.

This is some placeholder content the Profile tabâs associated content.

This is some placeholder content the Contact tabâs associated content.

This is some placeholder content the Disabled tabâs associated content.

`} /> + +And with vertical pills. Ideally, for vertical tabs, you should also add `aria-orientation="vertical"` to the tab list container. + + +

+ + + + + +

This is some placeholder content the Home tabâs associated content.

This is some placeholder content the Profile tabâs associated content.

This is some placeholder content the Disabled tabâs associated content.

This is some placeholder content the Messages tabâs associated content.

This is some placeholder content the Settings tabâs associated content.

`} /> + +## List groups + +The tab plugin also works with [list groups]([[docsref:/components/list-group]]). Add `data-bs-toggle="tab"` to each `.list-group-item` and pair them with `.tab-pane` elements. + + +

+ Home + Profile + Messages + Settings +

Some placeholder content in a paragraph relating to "Home".

Some placeholder content in a paragraph relating to "Profile".

Some placeholder content in a paragraph relating to "Messages".

Some placeholder content in a paragraph relating to "Settings".

+`} /> + +## Accessibility + +Dynamic tabbed interfaces, as described in the [ARIA Authoring Practices Guide tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/), 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 ` + +

+ +

+ + + +

...

+``` + +### Via JavaScript + +Enable tabbable tabs via JavaScript (each tab needs to be activated individually): + +```js +const triggerTabList = document.querySelectorAll('#myTab button') +triggerTabList.forEach(triggerEl => { + const tabTrigger = new bootstrap.Tab(triggerEl) + + triggerEl.addEventListener('click', event => { + event.preventDefault() + tabTrigger.show() + }) +}) +``` + +You can activate individual tabs in several ways: + +```js +const triggerEl = document.querySelector('#myTab button[data-bs-target="#profile"]') +bootstrap.Tab.getInstance(triggerEl).show() // Select tab by name + +const triggerFirstTabEl = document.querySelector('#myTab li:first-child button') +bootstrap.Tab.getInstance(triggerFirstTabEl).show() // Select first tab +``` + +### Fade effect + +To make tabs fade in, add `.fade` to each `.tab-pane`. The first tab pane must also have `.show` to make the initial content visible. + +```html +

...

+``` + +### Methods + + + +Activates your content as a tab element. + +You can create a tab instance with the constructor, for example: + +```js +const bsTab = new bootstrap.Tab('#myTab') +``` + + +| Method | Description | +| --- | --- | +| `dispose` | Destroys an elementâs tab. | +| `getInstance` | Static method which allows you to get the tab instance associated with a DOM element, you can use it like this: `bootstrap.Tab.getInstance(element)`. | +| `getOrCreateInstance` | Static method which returns a tab instance associated to a DOM element or create a new one in case it wasnât initialized. You can use it like this: `bootstrap.Tab.getOrCreateInstance(element)`. | +| `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.bs.tab` event occurs). | + + +### Events + +When showing a new tab, the events fire in the following order: + +1. `hide.bs.tab` (on the current active tab) +2. `show.bs.tab` (on the to-be-shown tab) +3. `hidden.bs.tab` (on the previous active tab, the same one as for the `hide.bs.tab` event) +4. `shown.bs.tab` (on the newly-active just-shown tab, the same one as for the `show.bs.tab` event) + +If no tab was already active, then the `hide.bs.tab` and `hidden.bs.tab` events will not be fired. + + +| Event type | Description | +| --- | --- | +| `hide.bs.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.bs.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. | +| `show.bs.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.bs.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. | + + +```js +const tabEl = document.querySelector('button[data-bs-toggle="tab"]') +tabEl.addEventListener('shown.bs.tab', event => { + event.target // newly activated tab + event.relatedTarget // previous active tab +}) +``` diff --git a/site/src/content/docs/components/toasts.mdx b/site/src/content/docs/components/toasts.mdx index f029103d30..e20f1e3c62 100644 --- a/site/src/content/docs/components/toasts.mdx +++ b/site/src/content/docs/components/toasts.mdx @@ -321,6 +321,17 @@ const toastElList = document.querySelectorAll('.toast') const toastList = [...toastElList].map(toastEl => new bootstrap.Toast(toastEl, option)) ``` +### Via data attributes + + +| Attribute | Description | +| --- | --- | +| `data-bs-dismiss="toast"` | On a close control, dismisses the toast when activated. | +| `data-bs-autohide` | Whether the toast hides automatically after the delay. | +| `data-bs-delay` | Time in milliseconds before hiding (when autohide is enabled). | +| `data-bs-animation` | Whether to use the fade transition when showing and hiding. | + + ### Triggers diff --git a/site/src/content/docs/components/toggler.mdx b/site/src/content/docs/components/toggler.mdx index 5a4341a9a4..ace15989ca 100644 --- a/site/src/content/docs/components/toggler.mdx +++ b/site/src/content/docs/components/toggler.mdx @@ -82,6 +82,15 @@ You could also use this to toggle the `disabled` attribute on a `fieldset` eleme Add `data-bs-toggle="toggler"` to the element to automatically. The `data-bs-target` is optional, and attribute accepts a CSS selector to apply the toggler functionality to. Be sure to add the `data-bs-attribute` and `data-bs-value` attributes to the toggled element's markup. + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="toggler"` | Initializes the toggler on the trigger element. | +| `data-bs-target` | Optional CSS selector for the element whose attribute is toggled. | +| `data-bs-attribute` | Name of the HTML attribute to toggle (e.g. `hidden`, `disabled`). | +| `data-bs-value` | Value to set when the attribute is âonâ (often paired with removal when âoffâ). | + + ### Via JavaScript We don't recommend using this component programmatically, as the initial purpose of it is to avoid using JavaScript. However, you can enable manually with: diff --git a/site/src/content/docs/components/tooltip.mdx b/site/src/content/docs/components/tooltip.mdx index 83b8331776..cddb5a7c43 100644 --- a/site/src/content/docs/components/tooltip.mdx +++ b/site/src/content/docs/components/tooltip.mdx @@ -166,6 +166,18 @@ const tooltip = new bootstrap.Tooltip('#example', { +### Via data attributes + + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="tooltip"` | Initializes the tooltip on the trigger element. | +| `data-bs-title` | Text (or HTML when allowed) shown in the tooltip body. | +| `data-bs-placement` | Where to place the tooltip (`top`, `right`, `bottom`, `left`, or responsive variants). | +| `data-bs-custom-class` | Extra class names added to the tooltip for theming. | +| `data-bs-html` | When `true`, allows HTML in the title (use with care; prefer plain text for user content). | + + ### Markup The required markup for a tooltip is only a `data` attribute and `title` on the HTML element you wish to have a tooltip. The generated markup of a tooltip is rather simple, though it does require a position (by default, set to `top` by the plugin). diff --git a/site/src/content/docs/forms/chip-input.mdx b/site/src/content/docs/forms/chip-input.mdx index 0dab11a655..bf381ccf40 100644 --- a/site/src/content/docs/forms/chip-input.mdx +++ b/site/src/content/docs/forms/chip-input.mdx @@ -183,6 +183,16 @@ Disable the ghost input to prevent adding new chips. Existing chips become non-i Add `data-bs-chip-input` to your container element to automatically initialize the chip input behavior. Options can be passed as data attributes. + +| Attribute | Description | +| --- | --- | +| `data-bs-chip-input` | Initializes the chip input on the container element. | +| `data-bs-separator` | Character that creates a new chip when typed (or `null` to disable). | +| `data-bs-allow-duplicates` | Whether duplicate chip values are allowed. | +| `data-bs-max-chips` | Maximum number of chips (`null` for no limit). | +| `data-bs-create-on-blur` | Create a chip from the input value when focus leaves the field. | + + ```html

diff --git a/site/src/content/docs/forms/combobox.mdx b/site/src/content/docs/forms/combobox.mdx index 435f6e8f06..db8c5fe6c4 100644 --- a/site/src/content/docs/forms/combobox.mdx +++ b/site/src/content/docs/forms/combobox.mdx @@ -371,6 +371,19 @@ For multiple selection, the hidden input value is a comma-separated list of sele ## JavaScript +### Via data attributes + + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="combobox"` | Initializes the combobox on the toggle button. | +| `data-bs-value` | On a `.menu-item`, the value submitted and shown when that option is selected. | +| `data-bs-search` | Enables the search/filter field inside the menu. | +| `data-bs-multiple` | Enables multi-select behavior. | +| `data-bs-name` | `name` of the auto-created hidden input for form submission. | +| `data-bs-placeholder` | Placeholder text shown in the toggle when nothing is selected. | + + ### Options Options can be passed via data attributes on the toggle button (e.g., `data-bs-search="true"`) or as a config object when initializing via JavaScript. diff --git a/site/src/content/docs/forms/datepicker.mdx b/site/src/content/docs/forms/datepicker.mdx index d9002775b5..f3e11b423e 100644 --- a/site/src/content/docs/forms/datepicker.mdx +++ b/site/src/content/docs/forms/datepicker.mdx @@ -199,6 +199,13 @@ Use `data-bs-datepicker-theme` to set the datepicker popup's theme independently Add `data-bs-toggle="datepicker"` to any input element to initialize it as a datepicker. + +| Attribute | Description | +| --- | --- | +| `data-bs-toggle="datepicker"` | Initializes the datepicker on the input (or button) element. | +| `data-bs-inline` | When `true`, renders the calendar inline instead of a popup. | + + ```html ``` diff --git a/site/src/content/docs/forms/otp-input.mdx b/site/src/content/docs/forms/otp-input.mdx index d62afd9d96..9eab44a878 100644 --- a/site/src/content/docs/forms/otp-input.mdx +++ b/site/src/content/docs/forms/otp-input.mdx @@ -171,6 +171,13 @@ Use a form label and help text for better accessibility. Add `data-bs-otp` to your container element to automatically initialize the OTP input behavior. + +| Attribute | Description | +| --- | --- | +| `data-bs-otp` | Initializes the OTP input on the container wrapping the digit fields. | +| `data-bs-mask` | When `true`, uses password fields to mask entered digits. | + + ```html

diff --git a/site/src/content/docs/forms/password-strength.mdx b/site/src/content/docs/forms/password-strength.mdx index b38bf99538..454502b662 100644 --- a/site/src/content/docs/forms/password-strength.mdx +++ b/site/src/content/docs/forms/password-strength.mdx @@ -149,6 +149,14 @@ The default scoring algorithm evaluates passwords based on: Add `data-bs-strength` to automatically initialize. The component will look for a password input in the same parent container. + +| Attribute | Description | +| --- | --- | +| `data-bs-strength` | Initializes the strength indicator on the element (usually `.strength`). | +| `data-bs-input` | CSS selector for the password field when it is not a sibling in the same container. | +| `data-bs-min-length` | Minimum length used when computing the strength score. | + + ```html

diff --git a/site/src/content/docs/getting-started/javascript.mdx b/site/src/content/docs/getting-started/javascript.mdx index 8b0a38d274..8c8e0ffb43 100644 --- a/site/src/content/docs/getting-started/javascript.mdx +++ b/site/src/content/docs/getting-started/javascript.mdx @@ -17,7 +17,7 @@ Curious which components explicitly require our JavaScript and Floating UI or Va - Menus for displaying and positioning (also requires [Floating UI](https://floating-ui.com/)) - Modals for displaying, positioning, and scroll behavior - Navbar for extending our Collapse and Offcanvas plugins to implement responsive behaviors -- Navs with the Tab plugin for toggling content panes +- [Nav]([[docsref:/components/nav]]) for navigation markup and styles; [Tab]([[docsref:/components/tab]]) plugin for toggling tab panes - Offcanvases for displaying, positioning, and scroll behavior - Scrollspy for scroll behavior and navigation updates - Toasts for displaying and dismissing diff --git a/site/src/scss/_component-examples.scss b/site/src/scss/_component-examples.scss index 5759d6a4a0..4600f08749 100644 --- a/site/src/scss/_component-examples.scss +++ b/site/src/scss/_component-examples.scss @@ -88,6 +88,13 @@ // margin-top: $spacer; // } + > .tab-content { + min-height: 120px; + padding: var(--bs-spacer); + background-color: var(--bs-bg-1); + @include border-radius(var(--bs-border-radius)); + } + > .menu.position-static { max-width: fit-content; }