diff options
Diffstat (limited to 'site/content/docs/5.2/components')
24 files changed, 8939 insertions, 0 deletions
diff --git a/site/content/docs/5.2/components/accordion.md b/site/content/docs/5.2/components/accordion.md new file mode 100644 index 0000000..2e24723 --- /dev/null +++ b/site/content/docs/5.2/components/accordion.md @@ -0,0 +1,165 @@ +--- +layout: docs +title: Accordion +description: Build vertically collapsing accordions in combination with our Collapse JavaScript plugin. +group: components +aliases: + - "/components/" + - "/docs/5.2/components/" +toc: true +--- + +## How it works + +The accordion uses [collapse]({{< docsref "/components/collapse" >}}) internally to make it collapsible. To render an accordion that's expanded, add the `.open` class on the `.accordion`. + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +## Example + +Click the accordions below to expand/collapse the accordion content. + +{{< example >}} +<div class="accordion" id="accordionExample"> + <div class="accordion-item"> + <h2 class="accordion-header" id="headingOne"> + <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#collapseOne" aria-expanded="true" aria-controls="collapseOne"> + Accordion Item #1 + </button> + </h2> + <div id="collapseOne" class="accordion-collapse collapse show" aria-labelledby="headingOne" data-bs-parent="#accordionExample"> + <div class="accordion-body"> + <strong>This is the first item's accordion body.</strong> It is shown by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow. + </div> + </div> + </div> + <div class="accordion-item"> + <h2 class="accordion-header" id="headingTwo"> + <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo"> + Accordion Item #2 + </button> + </h2> + <div id="collapseTwo" class="accordion-collapse collapse" aria-labelledby="headingTwo" data-bs-parent="#accordionExample"> + <div class="accordion-body"> + <strong>This is the second item's accordion body.</strong> It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow. + </div> + </div> + </div> + <div class="accordion-item"> + <h2 class="accordion-header" id="headingThree"> + <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseThree" aria-expanded="false" aria-controls="collapseThree"> + Accordion Item #3 + </button> + </h2> + <div id="collapseThree" class="accordion-collapse collapse" aria-labelledby="headingThree" data-bs-parent="#accordionExample"> + <div class="accordion-body"> + <strong>This is the third item's accordion body.</strong> It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow. + </div> + </div> + </div> +</div> +{{< /example >}} + +### Flush + +Add `.accordion-flush` to remove the default `background-color`, some borders, and some rounded corners to render accordions edge-to-edge with their parent container. + +{{< example class="bg-light" >}} +<div class="accordion accordion-flush" id="accordionFlushExample"> + <div class="accordion-item"> + <h2 class="accordion-header" id="flush-headingOne"> + <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseOne" aria-expanded="false" aria-controls="flush-collapseOne"> + Accordion Item #1 + </button> + </h2> + <div id="flush-collapseOne" class="accordion-collapse collapse" aria-labelledby="flush-headingOne" data-bs-parent="#accordionFlushExample"> + <div class="accordion-body">Placeholder content for this accordion, which is intended to demonstrate the <code>.accordion-flush</code> class. This is the first item's accordion body.</div> + </div> + </div> + <div class="accordion-item"> + <h2 class="accordion-header" id="flush-headingTwo"> + <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseTwo" aria-expanded="false" aria-controls="flush-collapseTwo"> + Accordion Item #2 + </button> + </h2> + <div id="flush-collapseTwo" class="accordion-collapse collapse" aria-labelledby="flush-headingTwo" data-bs-parent="#accordionFlushExample"> + <div class="accordion-body">Placeholder content for this accordion, which is intended to demonstrate the <code>.accordion-flush</code> class. This is the second item's accordion body. Let's imagine this being filled with some actual content.</div> + </div> + </div> + <div class="accordion-item"> + <h2 class="accordion-header" id="flush-headingThree"> + <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseThree" aria-expanded="false" aria-controls="flush-collapseThree"> + Accordion Item #3 + </button> + </h2> + <div id="flush-collapseThree" class="accordion-collapse collapse" aria-labelledby="flush-headingThree" data-bs-parent="#accordionFlushExample"> + <div class="accordion-body">Placeholder content for this accordion, which is intended to demonstrate the <code>.accordion-flush</code> class. This is the third item's accordion body. Nothing more exciting happening here in terms of content, but just filling up the space to make it look, at least at first glance, a bit more representative of how this would look in a real-world application.</div> + </div> + </div> +</div> +{{< /example >}} + +### Always open + +Omit the `data-bs-parent` attribute on each `.accordion-collapse` to make accordion items stay open when another item is opened. + +{{< example >}} +<div class="accordion" id="accordionPanelsStayOpenExample"> + <div class="accordion-item"> + <h2 class="accordion-header" id="panelsStayOpen-headingOne"> + <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#panelsStayOpen-collapseOne" aria-expanded="true" aria-controls="panelsStayOpen-collapseOne"> + Accordion Item #1 + </button> + </h2> + <div id="panelsStayOpen-collapseOne" class="accordion-collapse collapse show" aria-labelledby="panelsStayOpen-headingOne"> + <div class="accordion-body"> + <strong>This is the first item's accordion body.</strong> It is shown by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow. + </div> + </div> + </div> + <div class="accordion-item"> + <h2 class="accordion-header" id="panelsStayOpen-headingTwo"> + <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#panelsStayOpen-collapseTwo" aria-expanded="false" aria-controls="panelsStayOpen-collapseTwo"> + Accordion Item #2 + </button> + </h2> + <div id="panelsStayOpen-collapseTwo" class="accordion-collapse collapse" aria-labelledby="panelsStayOpen-headingTwo"> + <div class="accordion-body"> + <strong>This is the second item's accordion body.</strong> It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow. + </div> + </div> + </div> + <div class="accordion-item"> + <h2 class="accordion-header" id="panelsStayOpen-headingThree"> + <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#panelsStayOpen-collapseThree" aria-expanded="false" aria-controls="panelsStayOpen-collapseThree"> + Accordion Item #3 + </button> + </h2> + <div id="panelsStayOpen-collapseThree" class="accordion-collapse collapse" aria-labelledby="panelsStayOpen-headingThree"> + <div class="accordion-body"> + <strong>This is the third item's accordion body.</strong> It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow. + </div> + </div> + </div> +</div> +{{< /example >}} + +## Accessibility + +Please read the [collapse accessibility section]({{< docsref "/components/collapse#accessibility" >}}) for more information. + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, accordions now use local CSS variables on `.accordion` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="accordion-css-vars" file="scss/_accordion.scss" >}} + +### Sass variables + +{{< scss-docs name="accordion-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/components/alerts.md b/site/content/docs/5.2/components/alerts.md new file mode 100644 index 0000000..8837ed4 --- /dev/null +++ b/site/content/docs/5.2/components/alerts.md @@ -0,0 +1,257 @@ +--- +layout: docs +title: Alerts +description: Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages. +group: components +toc: true +--- + +## Examples + +Alerts are available for any length of text, as well as an optional close button. For proper styling, use one of the eight **required** contextual classes (e.g., `.alert-success`). For inline dismissal, use the [alerts JavaScript plugin](#dismissing). + +{{< example >}} +{{< alerts.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<div class="alert alert-{{ .name }}" role="alert"> + A simple {{ .name }} alert—check it out! +</div>{{- end -}} +{{< /alerts.inline >}} +{{< /example >}} + +{{< callout info >}} +{{< partial "callout-warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +### Live example + +Click the button below to show an alert (hidden with inline styles to start), then dismiss (and destroy) it with the built-in close button. + +{{< example stackblitz_add_js="true" >}} +<div id="liveAlertPlaceholder"></div> +<button type="button" class="btn btn-primary" id="liveAlertBtn">Show live alert</button> +{{< /example >}} + +We use the following JavaScript to trigger our live alert demo: + +```js +const alertPlaceholder = document.getElementById('liveAlertPlaceholder') + +const alert = (message, type) => { + const wrapper = document.createElement('div') + wrapper.innerHTML = [ + `<div class="alert alert-${type} alert-dismissible" role="alert">`, + ` <div>${message}</div>`, + ' <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>', + '</div>' + ].join('') + + alertPlaceholder.append(wrapper) +} + +const alertTrigger = document.getElementById('liveAlertBtn') +if (alertTrigger) { + alertTrigger.addEventListener('click', () => { + alert('Nice, you triggered this alert message!', 'success') + }) +} +``` + +### Link color + +Use the `.alert-link` utility class to quickly provide matching colored links within any alert. + +{{< example >}} +{{< alerts.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<div class="alert alert-{{ .name }}" role="alert"> + A simple {{ .name }} alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like. +</div>{{ end -}} +{{< /alerts.inline >}} +{{< /example >}} + +### Additional content + +Alerts can also contain additional HTML elements like headings, paragraphs and dividers. + +{{< example >}} +<div class="alert alert-success" role="alert"> + <h4 class="alert-heading">Well done!</h4> + <p>Aww yeah, you successfully read this important alert message. This example text is going to run a bit longer so that you can see how spacing within an alert works with this kind of content.</p> + <hr> + <p class="mb-0">Whenever you need to, be sure to use margin utilities to keep things nice and tidy.</p> +</div> +{{< /example >}} + +### Icons + +Similarly, you can use [flexbox utilities]({{< docsref "/utilities/flex" >}}) and [Bootstrap Icons]({{< param icons >}}) to create alerts with icons. Depending on your icons and content, you may want to add more utilities or custom styles. + +{{< example >}} +<div class="alert alert-primary d-flex align-items-center" role="alert"> + <svg xmlns="http://www.w3.org/2000/svg" class="bi bi-exclamation-triangle-fill flex-shrink-0 me-2" viewBox="0 0 16 16" role="img" aria-label="Warning:"> + <path d="M8.982 1.566a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995A.905.905 0 0 1 8 5zm.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2z"/> + </svg> + <div> + An example alert with an icon + </div> +</div> +{{< /example >}} + +Need more than one icon for your alerts? Consider using more Bootstrap Icons and making a local SVG sprite like so to easily reference the same icons repeatedly. + +{{< example >}} +<svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> + <symbol id="check-circle-fill" viewBox="0 0 16 16"> + <path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zm-3.97-3.03a.75.75 0 0 0-1.08.022L7.477 9.417 5.384 7.323a.75.75 0 0 0-1.06 1.06L6.97 11.03a.75.75 0 0 0 1.079-.02l3.992-4.99a.75.75 0 0 0-.01-1.05z"/> + </symbol> + <symbol id="info-fill" viewBox="0 0 16 16"> + <path d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194 0 .487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703 0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2z"/> + </symbol> + <symbol id="exclamation-triangle-fill" viewBox="0 0 16 16"> + <path d="M8.982 1.566a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995A.905.905 0 0 1 8 5zm.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2z"/> + </symbol> +</svg> + +<div class="alert alert-primary d-flex align-items-center" role="alert"> + <svg class="bi flex-shrink-0 me-2" role="img" aria-label="Info:"><use xlink:href="#info-fill"/></svg> + <div> + An example alert with an icon + </div> +</div> +<div class="alert alert-success d-flex align-items-center" role="alert"> + <svg class="bi flex-shrink-0 me-2" role="img" aria-label="Success:"><use xlink:href="#check-circle-fill"/></svg> + <div> + An example success alert with an icon + </div> +</div> +<div class="alert alert-warning d-flex align-items-center" role="alert"> + <svg class="bi flex-shrink-0 me-2" role="img" aria-label="Warning:"><use xlink:href="#exclamation-triangle-fill"/></svg> + <div> + An example warning alert with an icon + </div> +</div> +<div class="alert alert-danger d-flex align-items-center" role="alert"> + <svg class="bi flex-shrink-0 me-2" role="img" aria-label="Danger:"><use xlink:href="#exclamation-triangle-fill"/></svg> + <div> + An example danger alert with an icon + </div> +</div> +{{< /example >}} + +### Dismissing + +Using the alert JavaScript plugin, it's possible to dismiss any alert inline. Here's how: + +- Be sure you've loaded the alert plugin, or the compiled Bootstrap JavaScript. +- Add a [close button]({{< docsref "/components/close-button" >}}) and the `.alert-dismissible` class, which adds extra padding to the right of the alert and positions the close button. +- On the close button, add the `data-bs-dismiss="alert"` attribute, which triggers the JavaScript functionality. Be sure to use the `<button>` element with it for proper behavior across all devices. +- To animate alerts when dismissing them, be sure to add the `.fade` and `.show` classes. + +You can see this in action with a live demo: + +{{< example >}} +<div class="alert alert-warning alert-dismissible fade show" role="alert"> + <strong>Holy guacamole!</strong> You should check in on some of those fields below. + <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button> +</div> +{{< /example >}} + +{{< callout warning >}} +When an alert is dismissed, the element is completely removed from the page structure. If a keyboard user dismisses the alert using the close button, their focus will suddenly be lost and, depending on the browser, reset to the start of the page/document. For this reason, we recommend including additional JavaScript that listens for the `closed.bs.alert` event and programmatically sets `focus()` to the most appropriate location in the page. If you're planning to move focus to a non-interactive element that normally does not receive focus, make sure to add `tabindex="-1"` to the element. +{{< /callout >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, alerts now use local CSS variables on `.alert` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="alert-css-vars" file="scss/_alert.scss" >}} + +### Sass variables + +{{< scss-docs name="alert-variables" file="scss/_variables.scss" >}} + +### Sass mixin + +Used in combination with `$theme-colors` to create contextual modifier classes for our alerts. + +{{< scss-docs name="alert-variant-mixin" file="scss/mixins/_alert.scss" >}} + +### Sass loop + +Loop that generates the modifier classes with the `alert-variant()` mixin. + +{{< scss-docs name="alert-modifiers" file="scss/_alert.scss" >}} + +## JavaScript behavior + +### Initialize + +Initialize elements as alerts + +```js +const alertList = document.querySelectorAll('.alert') +const alerts = [...alertList].map(element => new bootstrap.Alert(element)) +``` + +{{< callout info >}} +For the sole purpose of dismissing an alert, it isn't necessary to initialize the component manually via the JS API. By making use of `data-bs-dismiss="alert"`, the component will be initialized automatically and properly dismissed. + +See the [triggers](#triggers) section for more details. +{{< /callout >}} + +### Triggers + +{{% js-dismiss "alert" %}} + +**Note that closing an alert will remove it from the DOM.** + +### Methods + +You can create an alert instance with the alert constructor, for example: + +```js +const bsAlert = new bootstrap.Alert('#myAlert') +``` + +This makes an alert listen for click events on descendant elements which have the `data-bs-dismiss="alert"` attribute. (Not necessary when using the data-api’s auto-initialization.) + +{{< bs-table >}} +| Method | Description | +| --- | --- | +| `close` | Closes an alert by removing it from the DOM. If the `.fade` and `.show` classes are present on the element, the alert will fade out before it is removed. | +| `dispose` | Destroys an element's alert. (Removes stored data on the DOM element) | +| `getInstance` | Static method which allows you to get the alert instance associated to a DOM element. For example: `bootstrap.Alert.getInstance(alert)`. | +| `getOrCreateInstance` | Static method which returns an alert instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `bootstrap.Alert.getOrCreateInstance(element)`. | +{{< /bs-table >}} + +Basic usage: + +```js +const alert = bootstrap.Alert.getOrCreateInstance('#myAlert') +alert.close() +``` + +### Events + +Bootstrap's alert plugin exposes a few events for hooking into alert functionality. + +{{< bs-table >}} +| Event | Description | +| --- | --- | +| `close.bs.alert` | Fires immediately when the `close` instance method is called. | +| `closed.bs.alert` | Fired when the alert has been closed and CSS transitions have completed. | +{{< /bs-table >}} + +```js +const myAlert = document.getElementById('myAlert') +myAlert.addEventListener('closed.bs.alert', event => { + // do something, for instance, explicitly move focus to the most appropriate element, + // so it doesn't get lost/reset to the start of the page + // document.getElementById('...').focus() +}) +``` diff --git a/site/content/docs/5.2/components/badge.md b/site/content/docs/5.2/components/badge.md new file mode 100644 index 0000000..55b1ffb --- /dev/null +++ b/site/content/docs/5.2/components/badge.md @@ -0,0 +1,103 @@ +--- +layout: docs +title: Badges +description: Documentation and examples for badges, our small count and labeling component. +group: components +toc: true +--- + +## Examples + +Badges scale to match the size of the immediate parent element by using relative font sizing and `em` units. As of v5, badges no longer have focus or hover styles for links. + +### Headings + +{{< example >}} +<h1>Example heading <span class="badge bg-secondary">New</span></h1> +<h2>Example heading <span class="badge bg-secondary">New</span></h2> +<h3>Example heading <span class="badge bg-secondary">New</span></h3> +<h4>Example heading <span class="badge bg-secondary">New</span></h4> +<h5>Example heading <span class="badge bg-secondary">New</span></h5> +<h6>Example heading <span class="badge bg-secondary">New</span></h6> +{{< /example >}} + +### Buttons + +Badges can be used as part of links or buttons to provide a counter. + +{{< example >}} +<button type="button" class="btn btn-primary"> + Notifications <span class="badge text-bg-secondary">4</span> +</button> +{{< /example >}} + +Note that depending on how they are used, badges may be confusing for users of screen readers and similar assistive technologies. While the styling of badges provides a visual cue as to their purpose, these users will simply be presented with the content of the badge. Depending on the specific situation, these badges may seem like random additional words or numbers at the end of a sentence, link, or button. + +Unless the context is clear (as with the "Notifications" example, where it is understood that the "4" is the number of notifications), consider including additional context with a visually hidden piece of additional text. + +### Positioned + +Use utilities to modify a `.badge` and position it in the corner of a link or button. + +{{< example >}} +<button type="button" class="btn btn-primary position-relative"> + Inbox + <span class="position-absolute top-0 start-100 translate-middle badge rounded-pill bg-danger"> + 99+ + <span class="visually-hidden">unread messages</span> + </span> +</button> +{{< /example >}} + +You can also replace the `.badge` class with a few more utilities without a count for a more generic indicator. + +{{< example >}} +<button type="button" class="btn btn-primary position-relative"> + Profile + <span class="position-absolute top-0 start-100 translate-middle p-2 bg-danger border border-light rounded-circle"> + <span class="visually-hidden">New alerts</span> + </span> +</button> +{{< /example >}} + +## Background colors + +{{< added-in "5.2.0" >}} + +Set a `background-color` with contrasting foreground `color` with [our `.text-bg-{color}` helpers]({{< docsref "helpers/color-background" >}}). Previously it was required to manually pair your choice of [`.text-{color}`]({{< docsref "/utilities/colors" >}}) and [`.bg-{color}`]({{< docsref "/utilities/background" >}}) utilities for styling, which you still may use if you prefer. + +{{< example >}} +{{< badge.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<span class="badge text-bg-{{ .name }}">{{ .name | title }}</span>{{- end -}} +{{< /badge.inline >}} +{{< /example >}} + +{{< callout info >}} +{{< partial "callout-warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## Pill badges + +Use the `.rounded-pill` utility class to make badges more rounded with a larger `border-radius`. + +{{< example >}} +{{< badge.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<span class="badge rounded-pill text-bg-{{ .name }}">{{ .name | title }}</span>{{- end -}} +{{< /badge.inline >}} +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, badges now use local CSS variables on `.badge` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="badge-css-vars" file="scss/_badge.scss" >}} + +### Sass variables + +{{< scss-docs name="badge-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/components/breadcrumb.md b/site/content/docs/5.2/components/breadcrumb.md new file mode 100644 index 0000000..0012f97 --- /dev/null +++ b/site/content/docs/5.2/components/breadcrumb.md @@ -0,0 +1,111 @@ +--- +layout: docs +title: Breadcrumb +description: Indicate the current page's location within a navigational hierarchy that automatically adds separators via CSS. +group: components +toc: true +--- + +## Example + +Use an ordered or unordered list with linked list items to create a minimally styled breadcrumb. Use our utilities to add additional styles as desired. + +{{< example >}} +<nav aria-label="breadcrumb"> + <ol class="breadcrumb"> + <li class="breadcrumb-item active" aria-current="page">Home</li> + </ol> +</nav> + +<nav aria-label="breadcrumb"> + <ol class="breadcrumb"> + <li class="breadcrumb-item"><a href="#">Home</a></li> + <li class="breadcrumb-item active" aria-current="page">Library</li> + </ol> +</nav> + +<nav aria-label="breadcrumb"> + <ol class="breadcrumb"> + <li class="breadcrumb-item"><a href="#">Home</a></li> + <li class="breadcrumb-item"><a href="#">Library</a></li> + <li class="breadcrumb-item active" aria-current="page">Data</li> + </ol> +</nav> +{{< /example >}} + +## Dividers + +Dividers are automatically added in CSS through [`::before`](https://developer.mozilla.org/en-US/docs/Web/CSS/::before) and [`content`](https://developer.mozilla.org/en-US/docs/Web/CSS/content). They can be changed by modifying a local CSS custom property `--bs-breadcrumb-divider`, or through the `$breadcrumb-divider` Sass variable — and `$breadcrumb-divider-flipped` for its RTL counterpart, if needed. We default to our Sass variable, which is set as a fallback to the custom property. This way, you get a global divider that you can override without recompiling CSS at any time. + +{{< example >}} +<nav style="--bs-breadcrumb-divider: '>';" aria-label="breadcrumb"> + <ol class="breadcrumb"> + <li class="breadcrumb-item"><a href="#">Home</a></li> + <li class="breadcrumb-item active" aria-current="page">Library</li> + </ol> +</nav> +{{< /example >}} + +When modifying via Sass, the [quote](https://sass-lang.com/documentation/modules/string#quote) function is required to generate the quotes around a string. For example, using `>` as the divider, you can use this: + +```scss +$breadcrumb-divider: quote(">"); +``` + +It's also possible to use an **embedded SVG icon**. Apply it via our CSS custom property, or use the Sass variable. + + +{{< callout info >}} +### Using embedded SVG + +Inlining SVG as data URI requires to URL escape a few characters, most notably `<`, `>` and `#`. That's why the `$breadcrumb-divider` variable is passed through our [`escape-svg()` Sass function]({{< docsref "/customize/sass#escape-svg" >}}). When using the CSS custom property, you need to URL escape your SVG on your own. Read [Kevin Weber's explanations on CodePen](https://codepen.io/kevinweber/pen/dXWoRw ) for detailed information on what to escape. +{{< /callout >}} + +{{< example >}} +<nav style="--bs-breadcrumb-divider: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='8' height='8'%3E%3Cpath d='M2.5 0L1 1.5 3.5 4 1 6.5 2.5 8l4-4-4-4z' fill='%236c757d'/%3E%3C/svg%3E");" aria-label="breadcrumb"> + <ol class="breadcrumb"> + <li class="breadcrumb-item"><a href="#">Home</a></li> + <li class="breadcrumb-item active" aria-current="page">Library</li> + </ol> +</nav> +{{< /example >}} + +```scss +$breadcrumb-divider: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='8' height='8'><path d='M2.5 0L1 1.5 3.5 4 1 6.5 2.5 8l4-4-4-4z' fill='#{$breadcrumb-divider-color}'/></svg>"); +``` + +You can also remove the divider setting `--bs-breadcrumb-divider: '';` (empty strings in CSS custom properties counts as a value), or setting the Sass variable to `$breadcrumb-divider: none;`. + +{{< example >}} +<nav style="--bs-breadcrumb-divider: '';" aria-label="breadcrumb"> + <ol class="breadcrumb"> + <li class="breadcrumb-item"><a href="#">Home</a></li> + <li class="breadcrumb-item active" aria-current="page">Library</li> + </ol> +</nav> +{{< /example >}} + + +```scss +$breadcrumb-divider: none; +``` + +## Accessibility + +Since breadcrumbs provide a navigation, it's a good idea to add a meaningful label such as `aria-label="breadcrumb"` to describe the type of navigation provided in the `<nav>` element, as well as applying an `aria-current="page"` to the last item of the set to indicate that it represents the current page. + +For more information, see the [ARIA Authoring Practices Guide breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/). + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, breadcrumbs now use local CSS variables on `.breadcrumb` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="breadcrumb-css-vars" file="scss/_breadcrumb.scss" >}} + +### Sass variables + +{{< scss-docs name="breadcrumb-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/components/button-group.md b/site/content/docs/5.2/components/button-group.md new file mode 100644 index 0000000..8f7d2d6 --- /dev/null +++ b/site/content/docs/5.2/components/button-group.md @@ -0,0 +1,256 @@ +--- +layout: docs +title: Button group +description: Group a series of buttons together on a single line or stack them in a vertical column. +group: components +toc: true +--- + +## Basic example + +Wrap a series of buttons with `.btn` in `.btn-group`. + +{{< example >}} +<div class="btn-group" role="group" aria-label="Basic example"> + <button type="button" class="btn btn-primary">Left</button> + <button type="button" class="btn btn-primary">Middle</button> + <button type="button" class="btn btn-primary">Right</button> +</div> +{{< /example >}} + +{{< callout warning >}} +##### Ensure correct `role` and provide a label + +In order for assistive technologies (such as screen readers) to convey that a series of buttons is grouped, an appropriate `role` attribute needs to be provided. For button groups, this would be `role="group"`, while toolbars should have a `role="toolbar"`. + +In addition, groups and toolbars should be given an explicit label, as most assistive technologies will otherwise not announce them, despite the presence of the correct role attribute. In the examples provided here, we use `aria-label`, but alternatives such as `aria-labelledby` can also be used. +{{< /callout >}} + +These classes can also be added to groups of links, as an alternative to the [`.nav` navigation components]({{< docsref "/components/navs-tabs" >}}). + +{{< example >}} +<div class="btn-group"> + <a href="#" class="btn btn-primary active" aria-current="page">Active link</a> + <a href="#" class="btn btn-primary">Link</a> + <a href="#" class="btn btn-primary">Link</a> +</div> +{{< /example >}} + +## Mixed styles + +{{< example >}} +<div class="btn-group" role="group" aria-label="Basic mixed styles example"> + <button type="button" class="btn btn-danger">Left</button> + <button type="button" class="btn btn-warning">Middle</button> + <button type="button" class="btn btn-success">Right</button> +</div> +{{< /example >}} + +## Outlined styles + +{{< example >}} +<div class="btn-group" role="group" aria-label="Basic outlined example"> + <button type="button" class="btn btn-outline-primary">Left</button> + <button type="button" class="btn btn-outline-primary">Middle</button> + <button type="button" class="btn btn-outline-primary">Right</button> +</div> +{{< /example >}} + +## Checkbox and radio button groups + +Combine button-like checkbox and radio [toggle buttons]({{< docsref "/forms/checks-radios" >}}) into a seamless looking button group. + +{{< example >}} +<div class="btn-group" role="group" aria-label="Basic checkbox toggle button group"> + <input type="checkbox" class="btn-check" id="btncheck1" autocomplete="off"> + <label class="btn btn-outline-primary" for="btncheck1">Checkbox 1</label> + + <input type="checkbox" class="btn-check" id="btncheck2" autocomplete="off"> + <label class="btn btn-outline-primary" for="btncheck2">Checkbox 2</label> + + <input type="checkbox" class="btn-check" id="btncheck3" autocomplete="off"> + <label class="btn btn-outline-primary" for="btncheck3">Checkbox 3</label> +</div> +{{< /example >}} + +{{< example >}} +<div class="btn-group" role="group" aria-label="Basic radio toggle button group"> + <input type="radio" class="btn-check" name="btnradio" id="btnradio1" autocomplete="off" checked> + <label class="btn btn-outline-primary" for="btnradio1">Radio 1</label> + + <input type="radio" class="btn-check" name="btnradio" id="btnradio2" autocomplete="off"> + <label class="btn btn-outline-primary" for="btnradio2">Radio 2</label> + + <input type="radio" class="btn-check" name="btnradio" id="btnradio3" autocomplete="off"> + <label class="btn btn-outline-primary" for="btnradio3">Radio 3</label> +</div> +{{< /example >}} + +## Button toolbar + +Combine sets of button groups into button toolbars for more complex components. Use utility classes as needed to space out groups, buttons, and more. + +{{< example >}} +<div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups"> + <div class="btn-group me-2" role="group" aria-label="First group"> + <button type="button" class="btn btn-primary">1</button> + <button type="button" class="btn btn-primary">2</button> + <button type="button" class="btn btn-primary">3</button> + <button type="button" class="btn btn-primary">4</button> + </div> + <div class="btn-group me-2" role="group" aria-label="Second group"> + <button type="button" class="btn btn-secondary">5</button> + <button type="button" class="btn btn-secondary">6</button> + <button type="button" class="btn btn-secondary">7</button> + </div> + <div class="btn-group" role="group" aria-label="Third group"> + <button type="button" class="btn btn-info">8</button> + </div> +</div> +{{< /example >}} + +Feel free to mix input groups with button groups in your toolbars. Similar to the example above, you'll likely need some utilities though to space things properly. + +{{< example >}} +<div class="btn-toolbar mb-3" role="toolbar" aria-label="Toolbar with button groups"> + <div class="btn-group me-2" role="group" aria-label="First group"> + <button type="button" class="btn btn-outline-secondary">1</button> + <button type="button" class="btn btn-outline-secondary">2</button> + <button type="button" class="btn btn-outline-secondary">3</button> + <button type="button" class="btn btn-outline-secondary">4</button> + </div> + <div class="input-group"> + <div class="input-group-text" id="btnGroupAddon">@</div> + <input type="text" class="form-control" placeholder="Input group example" aria-label="Input group example" aria-describedby="btnGroupAddon"> + </div> +</div> + +<div class="btn-toolbar justify-content-between" role="toolbar" aria-label="Toolbar with button groups"> + <div class="btn-group" role="group" aria-label="First group"> + <button type="button" class="btn btn-outline-secondary">1</button> + <button type="button" class="btn btn-outline-secondary">2</button> + <button type="button" class="btn btn-outline-secondary">3</button> + <button type="button" class="btn btn-outline-secondary">4</button> + </div> + <div class="input-group"> + <div class="input-group-text" id="btnGroupAddon2">@</div> + <input type="text" class="form-control" placeholder="Input group example" aria-label="Input group example" aria-describedby="btnGroupAddon2"> + </div> +</div> +{{< /example >}} + +## Sizing + +Instead of applying button sizing classes to every button in a group, just add `.btn-group-*` to each `.btn-group`, including each one when nesting multiple groups. + +{{< example >}} +<div class="btn-group btn-group-lg" role="group" aria-label="Large button group"> + <button type="button" class="btn btn-outline-dark">Left</button> + <button type="button" class="btn btn-outline-dark">Middle</button> + <button type="button" class="btn btn-outline-dark">Right</button> +</div> +<br> +<div class="btn-group" role="group" aria-label="Default button group"> + <button type="button" class="btn btn-outline-dark">Left</button> + <button type="button" class="btn btn-outline-dark">Middle</button> + <button type="button" class="btn btn-outline-dark">Right</button> +</div> +<br> +<div class="btn-group btn-group-sm" role="group" aria-label="Small button group"> + <button type="button" class="btn btn-outline-dark">Left</button> + <button type="button" class="btn btn-outline-dark">Middle</button> + <button type="button" class="btn btn-outline-dark">Right</button> +</div> +{{< /example >}} + +## Nesting + +Place a `.btn-group` within another `.btn-group` when you want dropdown menus mixed with a series of buttons. + +{{< example >}} +<div class="btn-group" role="group" aria-label="Button group with nested dropdown"> + <button type="button" class="btn btn-primary">1</button> + <button type="button" class="btn btn-primary">2</button> + + <div class="btn-group" role="group"> + <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + </ul> + </div> +</div> +{{< /example >}} + +## Vertical variation + +Make a set of buttons appear vertically stacked rather than horizontally. **Split button dropdowns are not supported here.** + +{{< example >}} +<div class="btn-group-vertical" role="group" aria-label="Vertical button group"> + <button type="button" class="btn btn-dark">Button</button> + <button type="button" class="btn btn-dark">Button</button> + <button type="button" class="btn btn-dark">Button</button> + <button type="button" class="btn btn-dark">Button</button> + <button type="button" class="btn btn-dark">Button</button> + <button type="button" class="btn btn-dark">Button</button> +</div> +{{< /example >}} + +{{< example >}} +<div class="btn-group-vertical" role="group" aria-label="Vertical button group"> + <button type="button" class="btn btn-primary">Button</button> + <button type="button" class="btn btn-primary">Button</button> + <div class="btn-group" role="group"> + <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + </ul> + </div> + <button type="button" class="btn btn-primary">Button</button> + <button type="button" class="btn btn-primary">Button</button> + <div class="btn-group" role="group"> + <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + </ul> + </div> + <div class="btn-group" role="group"> + <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + </ul> + </div> + <div class="btn-group" role="group"> + <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + <li><a class="dropdown-item" href="#">Dropdown link</a></li> + </ul> + </div> +</div> +{{< /example >}} + +{{< example >}} +<div class="btn-group-vertical" role="group" aria-label="Vertical radio toggle button group"> + <input type="radio" class="btn-check" name="vbtn-radio" id="vbtn-radio1" autocomplete="off" checked> + <label class="btn btn-outline-danger" for="vbtn-radio1">Radio 1</label> + <input type="radio" class="btn-check" name="vbtn-radio" id="vbtn-radio2" autocomplete="off"> + <label class="btn btn-outline-danger" for="vbtn-radio2">Radio 2</label> + <input type="radio" class="btn-check" name="vbtn-radio" id="vbtn-radio3" autocomplete="off"> + <label class="btn btn-outline-danger" for="vbtn-radio3">Radio 3</label> +</div> +{{< /example >}} diff --git a/site/content/docs/5.2/components/buttons.md b/site/content/docs/5.2/components/buttons.md new file mode 100644 index 0000000..c2fdd75 --- /dev/null +++ b/site/content/docs/5.2/components/buttons.md @@ -0,0 +1,242 @@ +--- +layout: docs +title: Buttons +description: Use Bootstrap's custom button styles for actions in forms, dialogs, and more with support for multiple sizes, states, and more. +group: components +toc: true +--- + +## Examples + +Bootstrap includes several predefined button styles, each serving its own semantic purpose, with a few extras thrown in for more control. + +{{< example >}} +{{< buttons.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<button type="button" class="btn btn-{{ .name }}">{{ .name | title }}</button> +{{- end -}} +{{< /buttons.inline >}} + +<button type="button" class="btn btn-link">Link</button> +{{< /example >}} + +{{< callout info >}} +{{< partial "callout-warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## Disable text wrapping + +If you don't want the button text to wrap, you can add the `.text-nowrap` class to the button. In Sass, you can set `$btn-white-space: nowrap` to disable text wrapping for each button. + +## Button tags + +The `.btn` classes are designed to be used with the `<button>` element. However, you can also use these classes on `<a>` or `<input>` elements (though some browsers may apply a slightly different rendering). + +When using button classes on `<a>` elements that are used to trigger in-page functionality (like collapsing content), rather than linking to new pages or sections within the current page, these links should be given a `role="button"` to appropriately convey their purpose to assistive technologies such as screen readers. + +{{< example >}} +<a class="btn btn-primary" href="#" role="button">Link</a> +<button class="btn btn-primary" type="submit">Button</button> +<input class="btn btn-primary" type="button" value="Input"> +<input class="btn btn-primary" type="submit" value="Submit"> +<input class="btn btn-primary" type="reset" value="Reset"> +{{< /example >}} + +## Outline buttons + +In need of a button, but not the hefty background colors they bring? Replace the default modifier classes with the `.btn-outline-*` ones to remove all background images and colors on any button. + +{{< example >}} +{{< buttons.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<button type="button" class="btn btn-outline-{{ .name }}">{{ .name | title }}</button> +{{- end -}} +{{< /buttons.inline >}} +{{< /example >}} + +{{< callout info >}} +Some of the button styles use a relatively light foreground color, and should only be used on a dark background in order to have sufficient contrast. +{{< /callout >}} + +## Sizes + +Fancy larger or smaller buttons? Add `.btn-lg` or `.btn-sm` for additional sizes. + +{{< example >}} +<button type="button" class="btn btn-primary btn-lg">Large button</button> +<button type="button" class="btn btn-secondary btn-lg">Large button</button> +{{< /example >}} + +{{< example >}} +<button type="button" class="btn btn-primary btn-sm">Small button</button> +<button type="button" class="btn btn-secondary btn-sm">Small button</button> +{{< /example >}} + +You can even roll your own custom sizing with CSS variables: + +{{< example >}} +<button type="button" class="btn btn-primary" + style="--bs-btn-padding-y: .25rem; --bs-btn-padding-x: .5rem; --bs-btn-font-size: .75rem;"> + Custom button +</button> +{{< /example >}} + +## Disabled state + +Make buttons look inactive by adding the `disabled` boolean attribute to any `<button>` element. Disabled buttons have `pointer-events: none` applied to, preventing hover and active states from triggering. + +{{< example >}} +<button type="button" class="btn btn-primary" disabled>Primary button</button> +<button type="button" class="btn btn-secondary" disabled>Button</button> +<button type="button" class="btn btn-outline-primary" disabled>Primary button</button> +<button type="button" class="btn btn-outline-secondary" disabled>Button</button> +{{< /example >}} + +Disabled buttons using the `<a>` element behave a bit different: + +- `<a>`s don't support the `disabled` attribute, so you must add the `.disabled` class to make it visually appear disabled. +- Some future-friendly styles are included to disable all `pointer-events` on anchor buttons. +- Disabled buttons using `<a>` should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies. +- Disabled buttons using `<a>` *should not* include the `href` attribute. + +{{< example >}} +<a class="btn btn-primary disabled" role="button" aria-disabled="true">Primary link</a> +<a class="btn btn-secondary disabled" role="button" aria-disabled="true">Link</a> +{{< /example >}} + +### Link functionality caveat + +To cover cases where you have to keep the `href` attribute on a disabled link, the `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s. Note that this CSS property is not yet standardized for HTML, but all modern browsers support it. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, in addition to `aria-disabled="true"`, also include a `tabindex="-1"` attribute on these links to prevent them from receiving keyboard focus, and use custom JavaScript to disable their functionality altogether. + +{{< example >}} +<a href="#" class="btn btn-primary disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a> +<a href="#" class="btn btn-secondary disabled" tabindex="-1" role="button" aria-disabled="true">Link</a> +{{< /example >}} + +## Block buttons + +Create responsive stacks of full-width, "block buttons" like those in Bootstrap 4 with a mix of our display and gap utilities. By using utilities instead of button specific classes, we have much greater control over spacing, alignment, and responsive behaviors. + +{{< example >}} +<div class="d-grid gap-2"> + <button class="btn btn-primary" type="button">Button</button> + <button class="btn btn-primary" type="button">Button</button> +</div> +{{< /example >}} + +Here we create a responsive variation, starting with vertically stacked buttons until the `md` breakpoint, where `.d-md-block` replaces the `.d-grid` class, thus nullifying the `gap-2` utility. Resize your browser to see them change. + +{{< example >}} +<div class="d-grid gap-2 d-md-block"> + <button class="btn btn-primary" type="button">Button</button> + <button class="btn btn-primary" type="button">Button</button> +</div> +{{< /example >}} + +You can adjust the width of your block buttons with grid column width classes. For example, for a half-width "block button", use `.col-6`. Center it horizontally with `.mx-auto`, too. + +{{< example >}} +<div class="d-grid gap-2 col-6 mx-auto"> + <button class="btn btn-primary" type="button">Button</button> + <button class="btn btn-primary" type="button">Button</button> +</div> +{{< /example >}} + +Additional utilities can be used to adjust the alignment of buttons when horizontal. Here we've taken our previous responsive example and added some flex utilities and a margin utility on the button to right align the buttons when they're no longer stacked. + +{{< example >}} +<div class="d-grid gap-2 d-md-flex justify-content-md-end"> + <button class="btn btn-primary me-md-2" type="button">Button</button> + <button class="btn btn-primary" type="button">Button</button> +</div> +{{< /example >}} + +## Button plugin + +The button plugin allows you to create simple on/off toggle buttons. + +{{< callout info >}} +Visually, these toggle buttons are identical to the [checkbox toggle buttons]({{< docsref "/forms/checks-radios#checkbox-toggle-buttons" >}}). However, they are conveyed differently by assistive technologies: the checkbox toggles will be announced by screen readers as "checked"/"not checked" (since, despite their appearance, they are fundamentally still checkboxes), whereas these toggle buttons will be announced as "button"/"button pressed". The choice between these two approaches will depend on the type of toggle you are creating, and whether or not the toggle will make sense to users when announced as a checkbox or as an actual button. +{{< /callout >}} + +### Toggle states + +Add `data-bs-toggle="button"` to toggle a button's `active` state. If you're pre-toggling a button, you must manually add the `.active` class **and** `aria-pressed="true"` to ensure that it is conveyed appropriately to assistive technologies. + +{{< example >}} +<button type="button" class="btn btn-primary" data-bs-toggle="button">Toggle button</button> +<button type="button" class="btn btn-primary active" data-bs-toggle="button" aria-pressed="true">Active toggle button</button> +<button type="button" class="btn btn-primary" disabled data-bs-toggle="button">Disabled toggle button</button> +{{< /example >}} + +{{< example >}} +<a href="#" class="btn btn-primary" role="button" data-bs-toggle="button">Toggle link</a> +<a href="#" class="btn btn-primary active" role="button" data-bs-toggle="button" aria-pressed="true">Active toggle link</a> +<a class="btn btn-primary disabled" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a> +{{< /example >}} + +### Methods + +You can create a button instance with the button constructor, for example: + +```js +const bsButton = new bootstrap.Button('#myButton') +``` + +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `dispose` | Destroys an element's button. (Removes stored data on the DOM element) | +| `getInstance` | Static method which allows you to get the button instance associated to a DOM element, you can use it like this: `bootstrap.Button.getInstance(element)`. | +| `getOrCreateInstance` | Static method which returns a button instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `bootstrap.Button.getOrCreateInstance(element)`. | +| `toggle` | Toggles push state. Gives the button the appearance that it has been activated. | +{{< /bs-table >}} + +For example, to toggle all buttons + +```js +document.querySelectorAll('.btn').forEach(buttonElement => { + const button = bootstrap.Button.getOrCreateInstance(buttonElement) + button.toggle() +}) +``` + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, buttons now use local CSS variables on `.btn` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="btn-css-vars" file="scss/_buttons.scss" >}} + +Each `.btn-*` modifier class updates the appropriate CSS variables to minimize additional CSS rules with our `button-variant()`, `button-outline-variant()`, and `button-size()` mixins. + +Here's an example of building a custom `.btn-*` modifier class like we do for the buttons unique to our docs by reassigning Bootstrap's CSS variables with a mixture of our own CSS and Sass variables. + +<div class="bd-example"> + <button type="button" class="btn btn-bd-primary">Custom button</button> +</div> + +{{< scss-docs name="btn-css-vars-example" file="site/assets/scss/_buttons.scss" >}} + +### Sass variables + +{{< scss-docs name="btn-variables" file="scss/_variables.scss" >}} + +### Sass mixins + +There are three mixins for buttons: button and button outline variant mixins (both based on `$theme-colors`), plus a button size mixin. + +{{< scss-docs name="btn-variant-mixin" file="scss/mixins/_buttons.scss" >}} + +{{< scss-docs name="btn-outline-variant-mixin" file="scss/mixins/_buttons.scss" >}} + +{{< scss-docs name="btn-size-mixin" file="scss/mixins/_buttons.scss" >}} + +### Sass loops + +Button variants (for regular and outline buttons) use their respective mixins with our `$theme-colors` map to generate the modifier classes in `scss/_buttons.scss`. + +{{< scss-docs name="btn-variant-loops" file="scss/_buttons.scss" >}} diff --git a/site/content/docs/5.2/components/card.md b/site/content/docs/5.2/components/card.md new file mode 100644 index 0000000..6bc90e7 --- /dev/null +++ b/site/content/docs/5.2/components/card.md @@ -0,0 +1,739 @@ +--- +layout: docs +title: Cards +description: Bootstrap's cards provide a flexible and extensible content container with multiple variants and options. +group: components +toc: true +--- + +## About + +A **card** is a flexible and extensible content container. It includes options for headers and footers, a wide variety of content, contextual background colors, and powerful display options. If you're familiar with Bootstrap 3, cards replace our old panels, wells, and thumbnails. Similar functionality to those components is available as modifier classes for cards. + +## Example + +Cards are built with as little markup and styles as possible, but still manage to deliver a ton of control and customization. Built with flexbox, they offer easy alignment and mix well with other Bootstrap components. They have no `margin` by default, so use [spacing utilities]({{< docsref "/utilities/spacing" >}}) as needed. + +Below is an example of a basic card with mixed content and a fixed width. Cards have no fixed width to start, so they'll naturally fill the full width of its parent element. This is easily customized with our various [sizing options](#sizing). + +{{< example >}} +<div class="card" style="width: 18rem;"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> +{{< /example >}} + +## Content types + +Cards support a wide variety of content, including images, text, list groups, links, and more. Below are examples of what's supported. + +### Body + +The building block of a card is the `.card-body`. Use it whenever you need a padded section within a card. + +{{< example >}} +<div class="card"> + <div class="card-body"> + This is some text within a card body. + </div> +</div> +{{< /example >}} + +### Titles, text, and links + +Card titles are used by adding `.card-title` to a `<h*>` tag. In the same way, links are added and placed next to each other by adding `.card-link` to an `<a>` tag. + +Subtitles are used by adding a `.card-subtitle` to a `<h*>` tag. If the `.card-title` and the `.card-subtitle` items are placed in a `.card-body` item, the card title and subtitle are aligned nicely. + +{{< example >}} +<div class="card" style="width: 18rem;"> + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <h6 class="card-subtitle mb-2 text-muted">Card subtitle</h6> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + <a href="#" class="card-link">Card link</a> + <a href="#" class="card-link">Another link</a> + </div> +</div> +{{< /example >}} + +### Images + +`.card-img-top` places an image to the top of the card. With `.card-text`, text can be added to the card. Text within `.card-text` can also be styled with the standard HTML tags. + +{{< example >}} +<div class="card" style="width: 18rem;"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + </div> +</div> +{{< /example >}} + +### List groups + +Create lists of content in a card with a flush list group. + +{{< example >}} +<div class="card" style="width: 18rem;"> + <ul class="list-group list-group-flush"> + <li class="list-group-item">An item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> + </ul> +</div> +{{< /example >}} + +{{< example >}} +<div class="card" style="width: 18rem;"> + <div class="card-header"> + Featured + </div> + <ul class="list-group list-group-flush"> + <li class="list-group-item">An item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> + </ul> +</div> +{{< /example >}} + +{{< example >}} +<div class="card" style="width: 18rem;"> + <ul class="list-group list-group-flush"> + <li class="list-group-item">An item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> + </ul> + <div class="card-footer"> + Card footer + </div> +</div> +{{< /example >}} + +### Kitchen sink + +Mix and match multiple content types to create the card you need, or throw everything in there. Shown below are image styles, blocks, text styles, and a list group—all wrapped in a fixed-width card. + +{{< example >}} +<div class="card" style="width: 18rem;"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + </div> + <ul class="list-group list-group-flush"> + <li class="list-group-item">An item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> + </ul> + <div class="card-body"> + <a href="#" class="card-link">Card link</a> + <a href="#" class="card-link">Another link</a> + </div> +</div> +{{< /example >}} + +### Header and footer + +Add an optional header and/or footer within a card. + +{{< example >}} +<div class="card"> + <div class="card-header"> + Featured + </div> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> +{{< /example >}} + +Card headers can be styled by adding `.card-header` to `<h*>` elements. + +{{< example >}} +<div class="card"> + <h5 class="card-header">Featured</h5> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> +{{< /example >}} + +{{< example >}} +<div class="card"> + <div class="card-header"> + Quote + </div> + <div class="card-body"> + <blockquote class="blockquote mb-0"> + <p>A well-known quote, contained in a blockquote element.</p> + <footer class="blockquote-footer">Someone famous in <cite title="Source Title">Source Title</cite></footer> + </blockquote> + </div> +</div> +{{< /example >}} + +{{< example >}} +<div class="card text-center"> + <div class="card-header"> + Featured + </div> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> + <div class="card-footer text-muted"> + 2 days ago + </div> +</div> +{{< /example >}} + +## Sizing + +Cards assume no specific `width` to start, so they'll be 100% wide unless otherwise stated. You can change this as needed with custom CSS, grid classes, grid Sass mixins, or utilities. + +### Using grid markup + +Using the grid, wrap cards in columns and rows as needed. + +{{< example >}} +<div class="row"> + <div class="col-sm-6"> + <div class="card"> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> + </div> + </div> + <div class="col-sm-6"> + <div class="card"> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> + </div> + </div> +</div> +{{< /example >}} + +### Using utilities + +Use our handful of [available sizing utilities]({{< docsref "/utilities/sizing" >}}) to quickly set a card's width. + +{{< example >}} +<div class="card w-75"> + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Button</a> + </div> +</div> + +<div class="card w-50"> + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Button</a> + </div> +</div> +{{< /example >}} + +### Using custom CSS + +Use custom CSS in your stylesheets or as inline styles to set a width. + +{{< example >}} +<div class="card" style="width: 18rem;"> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> +{{< /example >}} + +## Text alignment + +You can quickly change the text alignment of any card—in its entirety or specific parts—with our [text align classes]({{< docsref "/utilities/text#text-alignment" >}}). + +{{< example >}} +<div class="card" style="width: 18rem;"> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> + +<div class="card text-center" style="width: 18rem;"> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> + +<div class="card text-end" style="width: 18rem;"> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> +{{< /example >}} + +## Navigation + +Add some navigation to a card's header (or block) with Bootstrap's [nav components]({{< docsref "/components/navs-tabs" >}}). + +{{< example >}} +<div class="card text-center"> + <div class="card-header"> + <ul class="nav nav-tabs card-header-tabs"> + <li class="nav-item"> + <a class="nav-link active" aria-current="true" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> + </ul> + </div> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> +{{< /example >}} + +{{< example >}} +<div class="card text-center"> + <div class="card-header"> + <ul class="nav nav-pills card-header-pills"> + <li class="nav-item"> + <a class="nav-link active" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> + </ul> + </div> + <div class="card-body"> + <h5 class="card-title">Special title treatment</h5> + <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> +{{< /example >}} + +## Images + +Cards include a few options for working with images. Choose from appending "image caps" at either end of a card, overlaying images with card content, or simply embedding the image in a card. + +### Image caps + +Similar to headers and footers, cards can include top and bottom "image caps"—images at the top or bottom of a card. + +{{< example >}} +<div class="card mb-3"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> + </div> +</div> +<div class="card"> + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> + </div> + {{< placeholder width="100%" height="180" class="card-img-bottom" text="Image cap" >}} +</div> +{{< /example >}} + +### Image overlays + +Turn an image into a card background and overlay your card's text. Depending on the image, you may or may not need additional styles or utilities. + +{{< example >}} +<div class="card text-bg-dark"> + {{< placeholder width="100%" height="270" class="bd-placeholder-img-lg card-img" text="Card image" >}} + <div class="card-img-overlay"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + <p class="card-text"><small>Last updated 3 mins ago</small></p> + </div> +</div> +{{< /example >}} + +{{< callout info >}} +Note that content should not be larger than the height of the image. If content is larger than the image the content will be displayed outside the image. +{{< /callout >}} + +## Horizontal + +Using a combination of grid and utility classes, cards can be made horizontal in a mobile-friendly and responsive way. In the example below, we remove the grid gutters with `.g-0` and use `.col-md-*` classes to make the card horizontal at the `md` breakpoint. Further adjustments may be needed depending on your card content. + +{{< example >}} +<div class="card mb-3" style="max-width: 540px;"> + <div class="row g-0"> + <div class="col-md-4"> + {{< placeholder width="100%" height="250" text="Image" class="img-fluid rounded-start" >}} + </div> + <div class="col-md-8"> + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> + </div> + </div> + </div> +</div> +{{< /example >}} + +## Card styles + +Cards include various options for customizing their backgrounds, borders, and color. + +### Background and color + +{{< added-in "5.2.0" >}} + +Set a `background-color` with contrasting foreground `color` with [our `.text-bg-{color}` helpers]({{< docsref "helpers/color-background" >}}). Previously it was required to manually pair your choice of [`.text-{color}`]({{< docsref "/utilities/colors" >}}) and [`.bg-{color}`]({{< docsref "/utilities/background" >}}) utilities for styling, which you still may use if you prefer. + +{{< example >}} +{{< card.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<div class="card text-bg-{{ .name }} mb-3" style="max-width: 18rem;"> + <div class="card-header">Header</div> + <div class="card-body"> + <h5 class="card-title">{{ .name | title }} card title</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + </div> +</div> +{{- end -}} +{{< /card.inline >}} +{{< /example >}} + +{{< callout info >}} +{{< partial "callout-warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +### Border + +Use [border utilities]({{< docsref "/utilities/borders" >}}) to change just the `border-color` of a card. Note that you can put `.text-{color}` classes on the parent `.card` or a subset of the card's contents as shown below. + +{{< example >}} +{{< card.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<div class="card border-{{ .name }} mb-3" style="max-width: 18rem;"> + <div class="card-header">Header</div> + <div class="card-body{{ if not .contrast_color }} text-{{ .name }}{{ end }}"> + <h5 class="card-title">{{ .name | title }} card title</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + </div> +</div> +{{- end -}} +{{< /card.inline >}} +{{< /example >}} + +### Mixins utilities + +You can also change the borders on the card header and footer as needed, and even remove their `background-color` with `.bg-transparent`. + +{{< example >}} +<div class="card border-success mb-3" style="max-width: 18rem;"> + <div class="card-header bg-transparent border-success">Header</div> + <div class="card-body text-success"> + <h5 class="card-title">Success card title</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + </div> + <div class="card-footer bg-transparent border-success">Footer</div> +</div> +{{< /example >}} + +## Card layout + +In addition to styling the content within cards, Bootstrap includes a few options for laying out series of cards. For the time being, **these layout options are not yet responsive**. + +### Card groups + +Use card groups to render cards as a single, attached element with equal width and height columns. Card groups start off stacked and use `display: flex;` to become attached with uniform dimensions starting at the `sm` breakpoint. + +{{< example >}} +<div class="card-group"> + <div class="card"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> + </div> + </div> + <div class="card"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This card has supporting text below as a natural lead-in to additional content.</p> + <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> + </div> + </div> + <div class="card"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This card has even longer content than the first to show that equal height action.</p> + <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> + </div> + </div> +</div> +{{< /example >}} + +When using card groups with footers, their content will automatically line up. + +{{< example >}} +<div class="card-group"> + <div class="card"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + <div class="card-footer"> + <small class="text-muted">Last updated 3 mins ago</small> + </div> + </div> + <div class="card"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This card has supporting text below as a natural lead-in to additional content.</p> + </div> + <div class="card-footer"> + <small class="text-muted">Last updated 3 mins ago</small> + </div> + </div> + <div class="card"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This card has even longer content than the first to show that equal height action.</p> + </div> + <div class="card-footer"> + <small class="text-muted">Last updated 3 mins ago</small> + </div> + </div> +</div> +{{< /example >}} + +### Grid cards + +Use the Bootstrap grid system and its [`.row-cols` classes]({{< docsref "/layout/grid#row-columns" >}}) to control how many grid columns (wrapped around your cards) you show per row. For example, here's `.row-cols-1` laying out the cards on one column, and `.row-cols-md-2` splitting four cards to equal width across multiple rows, from the medium breakpoint up. + +{{< example >}} +<div class="row row-cols-1 row-cols-md-2 g-4"> + <div class="col"> + <div class="card"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + </div> + </div> +</div> +{{< /example >}} + +Change it to `.row-cols-3` and you'll see the fourth card wrap. + +{{< example >}} +<div class="row row-cols-1 row-cols-md-3 g-4"> + <div class="col"> + <div class="card"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + </div> + </div> +</div> +{{< /example >}} + +When you need equal height, add `.h-100` to the cards. If you want equal heights by default, you can set `$card-height: 100%` in Sass. + +{{< example >}} +<div class="row row-cols-1 row-cols-md-3 g-4"> + <div class="col"> + <div class="card h-100"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card h-100"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a short card.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card h-100"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content.</p> + </div> + </div> + </div> + <div class="col"> + <div class="card h-100"> + {{< placeholder width="100%" height="140" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + </div> + </div> +</div> +{{< /example >}} + +Just like with card groups, card footers will automatically line up. + +{{< example >}} +<div class="row row-cols-1 row-cols-md-3 g-4"> + <div class="col"> + <div class="card h-100"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> + </div> + <div class="card-footer"> + <small class="text-muted">Last updated 3 mins ago</small> + </div> + </div> + </div> + <div class="col"> + <div class="card h-100"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This card has supporting text below as a natural lead-in to additional content.</p> + </div> + <div class="card-footer"> + <small class="text-muted">Last updated 3 mins ago</small> + </div> + </div> + </div> + <div class="col"> + <div class="card h-100"> + {{< placeholder width="100%" height="180" class="card-img-top" text="Image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This card has even longer content than the first to show that equal height action.</p> + </div> + <div class="card-footer"> + <small class="text-muted">Last updated 3 mins ago</small> + </div> + </div> + </div> +</div> +{{< /example >}} + +### Masonry + +In `v4` we used a CSS-only technique to mimic the behavior of [Masonry](https://masonry.desandro.com/)-like columns, but this technique came with lots of unpleasant [side effects](https://github.com/twbs/bootstrap/pull/28922). If you want to have this type of layout in `v5`, you can just make use of Masonry plugin. **Masonry is not included in Bootstrap**, but we've made a [demo example]({{< docsref "/examples/masonry" >}}) to help you get started. + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, cards now use local CSS variables on `.card` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="card-css-vars" file="scss/_card.scss" >}} + +### Sass variables + +{{< scss-docs name="card-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/components/carousel.md b/site/content/docs/5.2/components/carousel.md new file mode 100644 index 0000000..e32ce64 --- /dev/null +++ b/site/content/docs/5.2/components/carousel.md @@ -0,0 +1,385 @@ +--- +layout: docs +title: Carousel +description: A slideshow component for cycling through elements—images or slides of text—like a carousel. +group: components +toc: true +--- + +## How it works + +The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators. + +In browsers where the [Page Visibility API](https://www.w3.org/TR/page-visibility/) is supported, the carousel will avoid sliding when the webpage is not visible to the user (such as when the browser tab is inactive, the browser window is minimized, etc.). + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards. + +## Example + +Carousels don't automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. While carousels support previous/next controls and indicators, they're not explicitly required. Add and customize as you see fit. + +**The `.active` class needs to be added to one of the slides** otherwise the carousel will not be visible. Also be sure to set a unique `id` on the `.carousel` for optional controls, especially if you're using multiple carousels on a single page. Control and indicator elements must have a `data-bs-target` attribute (or `href` for links) that matches the `id` of the `.carousel` element. + +### Slides only + +Here's a carousel with slides only. Note the presence of the `.d-block` and `.w-100` on carousel images to prevent browser default image alignment. + +{{< example >}} +<div id="carouselExampleSlidesOnly" class="carousel slide" data-bs-ride="carousel"> + <div class="carousel-inner"> + <div class="carousel-item active"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#555" background="#777" text="First slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#444" background="#666" text="Second slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#333" background="#555" text="Third slide" >}} + </div> + </div> +</div> +{{< /example >}} + +### With controls + +Adding in the previous and next controls. We recommend using `<button>` elements, but you can also use `<a>` elements with `role="button"`. + +{{< example >}} +<div id="carouselExampleControls" class="carousel slide" data-bs-ride="carousel"> + <div class="carousel-inner"> + <div class="carousel-item active"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#555" background="#777" text="First slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#444" background="#666" text="Second slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#333" background="#555" text="Third slide" >}} + </div> + </div> + <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControls" data-bs-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> + <span class="visually-hidden">Previous</span> + </button> + <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControls" data-bs-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> + <span class="visually-hidden">Next</span> + </button> +</div> +{{< /example >}} + +### With indicators + +You can also add the indicators to the carousel, alongside the controls, too. + +{{< example >}} +<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="true"> + <div class="carousel-indicators"> + <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button> + <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="1" aria-label="Slide 2"></button> + <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="2" aria-label="Slide 3"></button> + </div> + <div class="carousel-inner"> + <div class="carousel-item active"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#555" background="#777" text="First slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#444" background="#666" text="Second slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#333" background="#555" text="Third slide" >}} + </div> + </div> + <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> + <span class="visually-hidden">Previous</span> + </button> + <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> + <span class="visually-hidden">Next</span> + </button> +</div> +{{< /example >}} + +### With captions + +Add captions to your slides easily with the `.carousel-caption` element within any `.carousel-item`. They can be easily hidden on smaller viewports, as shown below, with optional [display utilities]({{< docsref "/utilities/display" >}}). We hide them initially with `.d-none` and bring them back on medium-sized devices with `.d-md-block`. + +{{< example >}} +<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="false"> + <div class="carousel-indicators"> + <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button> + <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button> + <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button> + </div> + <div class="carousel-inner"> + <div class="carousel-item active"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#555" background="#777" text="First slide" >}} + <div class="carousel-caption d-none d-md-block"> + <h5>First slide label</h5> + <p>Some representative placeholder content for the first slide.</p> + </div> + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#444" background="#666" text="Second slide" >}} + <div class="carousel-caption d-none d-md-block"> + <h5>Second slide label</h5> + <p>Some representative placeholder content for the second slide.</p> + </div> + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#333" background="#555" text="Third slide" >}} + <div class="carousel-caption d-none d-md-block"> + <h5>Third slide label</h5> + <p>Some representative placeholder content for the third slide.</p> + </div> + </div> + </div> + <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> + <span class="visually-hidden">Previous</span> + </button> + <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> + <span class="visually-hidden">Next</span> + </button> +</div> +{{< /example >}} + +### Crossfade + +Add `.carousel-fade` to your carousel to animate slides with a fade transition instead of a slide. Depending on your carousel content (e.g., text only slides), you may want to add `.bg-body` or some custom CSS to the `.carousel-item`s for proper crossfading. + +{{< example >}} +<div id="carouselExampleFade" class="carousel slide carousel-fade" data-bs-ride="carousel"> + <div class="carousel-inner"> + <div class="carousel-item active"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#555" background="#777" text="First slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#444" background="#666" text="Second slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#333" background="#555" text="Third slide" >}} + </div> + </div> + <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> + <span class="visually-hidden">Previous</span> + </button> + <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> + <span class="visually-hidden">Next</span> + </button> +</div> +{{< /example >}} + +### Individual `.carousel-item` interval + +Add `data-bs-interval=""` to a `.carousel-item` to change the amount of time to delay between automatically cycling to the next item. + +{{< example >}} +<div id="carouselExampleInterval" class="carousel slide" data-bs-ride="carousel"> + <div class="carousel-inner"> + <div class="carousel-item active" data-bs-interval="10000"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#555" background="#777" text="First slide" >}} + </div> + <div class="carousel-item" data-bs-interval="2000"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#444" background="#666" text="Second slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#333" background="#555" text="Third slide" >}} + </div> + </div> + <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> + <span class="visually-hidden">Previous</span> + </button> + <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> + <span class="visually-hidden">Next</span> + </button> +</div> +{{< /example >}} + +### Disable touch swiping + +Carousels support swiping left/right on touchscreen devices to move between slides. This can be disabled using the `data-bs-touch` attribute. The example below also does not include the `data-bs-ride` attribute so it doesn't autoplay. + +{{< example >}} +<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="false"> + <div class="carousel-inner"> + <div class="carousel-item active"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#555" background="#777" text="First slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#444" background="#666" text="Second slide" >}} + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#333" background="#555" text="Third slide" >}} + </div> + </div> + <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> + <span class="visually-hidden">Previous</span> + </button> + <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> + <span class="visually-hidden">Next</span> + </button> +</div> +{{< /example >}} + +## Dark variant + +Add `.carousel-dark` to the `.carousel` for darker controls, indicators, and captions. Controls have been inverted from their default white fill with the `filter` CSS property. Captions and controls have additional Sass variables that customize the `color` and `background-color`. + +{{< example >}} +<div id="carouselExampleDark" class="carousel carousel-dark slide" data-bs-ride="carousel"> + <div class="carousel-indicators"> + <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button> + <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="1" aria-label="Slide 2"></button> + <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="2" aria-label="Slide 3"></button> + </div> + <div class="carousel-inner"> + <div class="carousel-item active" data-bs-interval="10000"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#aaa" background="#f5f5f5" text="First slide" >}} + <div class="carousel-caption d-none d-md-block"> + <h5>First slide label</h5> + <p>Some representative placeholder content for the first slide.</p> + </div> + </div> + <div class="carousel-item" data-bs-interval="2000"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#bbb" background="#eee" text="Second slide" >}} + <div class="carousel-caption d-none d-md-block"> + <h5>Second slide label</h5> + <p>Some representative placeholder content for the second slide.</p> + </div> + </div> + <div class="carousel-item"> + {{< placeholder width="800" height="400" class="bd-placeholder-img-lg d-block w-100" color="#999" background="#e5e5e5" text="Third slide" >}} + <div class="carousel-caption d-none d-md-block"> + <h5>Third slide label</h5> + <p>Some representative placeholder content for the third slide.</p> + </div> + </div> + </div> + <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> + <span class="visually-hidden">Previous</span> + </button> + <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> + <span class="visually-hidden">Next</span> + </button> +</div> +{{< /example >}} + +## Custom transition + +The transition duration of `.carousel-item` can be changed with the `$carousel-transition-duration` Sass variable before compiling or custom styles if you're using the compiled CSS. If multiple transitions are applied, make sure the transform transition is defined first (e.g. `transition: transform 2s ease, opacity .5s ease-out`). + +## Sass + +### Variables + +Variables for all carousels: + +{{< scss-docs name="carousel-variables" file="scss/_variables.scss" >}} + +Variables for the [dark carousel](#dark-variant): + +{{< scss-docs name="carousel-dark-variables" file="scss/_variables.scss" >}} + +## Usage + +### Via data attributes + +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`. + +The `data-bs-ride="carousel"` attribute is used to mark a carousel as animating starting at page load. If you don't use `data-bs-ride="carousel"` to initialize your carousel, you have to initialize it yourself. **It cannot be used in combination with (redundant and unnecessary) explicit JavaScript initialization of the same carousel.** + +### Via JavaScript + +Call carousel manually with: + +```js +const carousel = new bootstrap.Carousel('#myCarousel') +``` + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< bs-table >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `interval` | number | `5000` | The amount of time to delay between automatically cycling an item. | +| `keyboard` | boolean | `true` | Whether the carousel should react to keyboard events. | +| `pause` | string, boolean | `"hover"` | If set to `"hover"`, pauses the cycling of the carousel on `mouseenter` and resumes the cycling of the carousel on `mouseleave`. If set to `false`, hovering over the carousel won't pause it. On touch-enabled devices, when set to `"hover"`, cycling will pause on `touchend` (once the user finished interacting with the carousel) for two intervals, before automatically resuming. This is in addition to the mouse behavior. | +| `ride` | string, boolean | `false` | If set to `true`, autoplays the carousel after the user manually cycles the first item. If set to `"carousel"`, autoplays the carousel on load. | +| `touch` | boolean | `true` | Whether the carousel should support left/right swipe interactions on touchscreen devices. | +| `wrap` | boolean | `true` | Whether the carousel should cycle continuously or have hard stops. | +{{< /bs-table >}} + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +You can create a carousel instance with the carousel constructor, for example, to initialize with additional options and start cycling through items: + +```js +const myCarouselElement = document.querySelector('#myCarousel') +const carousel = new bootstrap.Carousel(myCarouselElement, { + interval: 2000, + wrap: false +}) +``` + +{{< bs-table >}} +| Method | Description | +| --- | --- | +| `cycle` | Cycles through the carousel items from left to right. | +| `dispose` | Destroys an element's carousel. (Removes stored data on the DOM element) | +| `getInstance` | Static method which allows you to get the carousel instance associated to a DOM element, you can use it like this: `bootstrap.Carousel.getInstance(element)`. | +| `getOrCreateInstance` | Static method which returns a carousel instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `bootstrap.Carousel.getOrCreateInstance(element)`. | +| `next` | Cycles to the next item. **Returns to the caller before the next item has been shown** (e.g., before the `slid.bs.carousel` event occurs). | +| `nextWhenVisible` | Don't cycle carousel to next when the page isn't visible or the carousel or its parent isn't visible. **Returns to the caller before the target item has been shown**. | +| `pause` | Stops the carousel from cycling through items. | +| `prev` | Cycles to the previous item. **Returns to the caller before the previous item has been shown** (e.g., before the `slid.bs.carousel` event occurs). | +| `to` | Cycles the carousel to a particular frame (0 based, similar to an array). **Returns to the caller before the target item has been shown** (e.g., before the `slid.bs.carousel` event occurs). | +{{< /bs-table >}} + +### Events + +Bootstrap's carousel class exposes two events for hooking into carousel functionality. Both events have the following additional properties: + +- `direction`: The direction in which the carousel is sliding (either `"left"` or `"right"`). +- `relatedTarget`: The DOM element that is being slid into place as the active item. +- `from`: The index of the current item +- `to`: The index of the next item + +All carousel events are fired at the carousel itself (i.e. at the `<div class="carousel">`). + +{{< bs-table >}} +| Event type | Description | +| --- | --- | +| `slid.bs.carousel` | Fired when the carousel has completed its slide transition. | +| `slide.bs.carousel` | Fires immediately when the `slide` instance method is invoked. | +{{< /bs-table >}} + +```js +const myCarousel = document.getElementById('myCarousel') + +myCarousel.addEventListener('slide.bs.carousel', event => { + // do something... +}) +``` diff --git a/site/content/docs/5.2/components/close-button.md b/site/content/docs/5.2/components/close-button.md new file mode 100644 index 0000000..f4a3ed0 --- /dev/null +++ b/site/content/docs/5.2/components/close-button.md @@ -0,0 +1,38 @@ +--- +layout: docs +title: Close button +description: A generic close button for dismissing content like modals and alerts. +group: components +toc: true +--- + +## Example + +Provide an option to dismiss or close a component with `.btn-close`. Default styling is limited, but highly customizable. Modify the Sass variables to replace the default `background-image`. **Be sure to include text for screen readers**, as we've done with `aria-label`. + +{{< example >}} +<button type="button" class="btn-close" aria-label="Close"></button> +{{< /example >}} + +## Disabled state + +Disabled close buttons change their `opacity`. We've also applied `pointer-events: none` and `user-select: none` to preventing hover and active states from triggering. + +{{< example >}} +<button type="button" class="btn-close" disabled aria-label="Close"></button> +{{< /example >}} + +## White variant + +Change the default `.btn-close` to be white with the `.btn-close-white` class. This class uses the `filter` property to invert the `background-image`. + +{{< example class="bg-dark" >}} +<button type="button" class="btn-close btn-close-white" aria-label="Close"></button> +<button type="button" class="btn-close btn-close-white" disabled aria-label="Close"></button> +{{< /example >}} + +## Sass + +### Variables + +{{< scss-docs name="close-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/components/collapse.md b/site/content/docs/5.2/components/collapse.md new file mode 100644 index 0000000..21be901 --- /dev/null +++ b/site/content/docs/5.2/components/collapse.md @@ -0,0 +1,198 @@ +--- +layout: docs +title: Collapse +description: Toggle the visibility of content across your project with a few classes and our JavaScript plugins. +group: components +toc: true +--- + +## How it works + +The collapse JavaScript plugin is used to show and hide content. Buttons or anchors are used as triggers that are mapped to specific elements you toggle. Collapsing an element will animate the `height` from its current value to `0`. Given how CSS handles animations, you cannot use `padding` on a `.collapse` element. Instead, use the class as an independent wrapping element. + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +## Example + +Click the buttons below to show and hide another element via class changes: + +- `.collapse` hides content +- `.collapsing` is applied during transitions +- `.collapse.show` shows content + +Generally, we recommend using a button with the `data-bs-target` attribute. While not recommended from a semantic point of view, you can also use a link with the `href` attribute (and a `role="button"`). In both cases, the `data-bs-toggle="collapse"` is required. + +{{< example >}} +<p> + <a class="btn btn-primary" data-bs-toggle="collapse" href="#collapseExample" role="button" aria-expanded="false" aria-controls="collapseExample"> + Link with href + </a> + <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample"> + Button with data-bs-target + </button> +</p> +<div class="collapse" id="collapseExample"> + <div class="card card-body"> + Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger. + </div> +</div> +{{< /example >}} + +## Horizontal + +The collapse plugin also supports horizontal collapsing. Add the `.collapse-horizontal` modifier class to transition the `width` instead of `height` and set a `width` on the immediate child element. Feel free to write your own custom Sass, use inline styles, or use our [width utilities]({{< docsref "/utilities/sizing" >}}). + +{{< callout info >}} +Please note that while the example below has a `min-height` set to avoid excessive repaints in our docs, this is not explicitly required. **Only the `width` on the child element is required.** +{{< /callout >}} + +{{< example >}} +<p> + <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseWidthExample" aria-expanded="false" aria-controls="collapseWidthExample"> + Toggle width collapse + </button> +</p> +<div style="min-height: 120px;"> + <div class="collapse collapse-horizontal" id="collapseWidthExample"> + <div class="card card-body" style="width: 300px;"> + This is some placeholder content for a horizontal collapse. It's hidden by default and shown when triggered. + </div> + </div> +</div> +{{< /example >}} + +## Multiple targets + +A `<button>` or `<a>` can show and hide multiple elements by referencing them with a selector in its `href` or `data-bs-target` attribute. +Multiple `<button>` or `<a>` can show and hide an element if they each reference it with their `href` or `data-bs-target` attribute + +{{< example >}} +<p> + <a class="btn btn-primary" data-bs-toggle="collapse" href="#multiCollapseExample1" role="button" aria-expanded="false" aria-controls="multiCollapseExample1">Toggle first element</a> + <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#multiCollapseExample2" aria-expanded="false" aria-controls="multiCollapseExample2">Toggle second element</button> + <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target=".multi-collapse" aria-expanded="false" aria-controls="multiCollapseExample1 multiCollapseExample2">Toggle both elements</button> +</p> +<div class="row"> + <div class="col"> + <div class="collapse multi-collapse" id="multiCollapseExample1"> + <div class="card card-body"> + Some placeholder content for the first collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger. + </div> + </div> + </div> + <div class="col"> + <div class="collapse multi-collapse" id="multiCollapseExample2"> + <div class="card card-body"> + Some placeholder content for the second collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger. + </div> + </div> + </div> +</div> +{{< /example >}} + +## Accessibility + +Be sure to add `aria-expanded` to the control element. This attribute explicitly conveys the current state of the collapsible element tied to the control to screen readers and similar assistive technologies. If the collapsible element is closed by default, the attribute on the control element should have a value of `aria-expanded="false"`. If you've set the collapsible element to be open by default using the `show` class, set `aria-expanded="true"` on the control instead. The plugin will automatically toggle this attribute on the control based on whether or not the collapsible element has been opened or closed (via JavaScript, or because the user triggered another control element also tied to the same collapsible element). If the control element's HTML element is not a button (e.g., an `<a>` or `<div>`), the attribute `role="button"` should be added to the element. + +If your control element is targeting a single collapsible element – i.e. the `data-bs-target` attribute is pointing to an `id` selector – you should add the `aria-controls` attribute to the control element, containing the `id` of the collapsible element. Modern screen readers and similar assistive technologies make use of this attribute to provide users with additional shortcuts to navigate directly to the collapsible element itself. + +Note that Bootstrap's current implementation does not cover the various *optional* keyboard interactions described in the [ARIA Authoring Practices Guide accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) - you will need to include these yourself with custom JavaScript. + +## Sass + +### Variables + +{{< scss-docs name="collapse-transition" file="scss/_variables.scss" >}} + +### Classes + +Collapse transition classes can be found in `scss/_transitions.scss` as these are shared across multiple components (collapse and accordion). + +{{< scss-docs name="collapse-classes" file="scss/_transitions.scss" >}} + +## Usage + +The collapse plugin utilizes a few classes to handle the heavy lifting: + +- `.collapse` hides the content +- `.collapse.show` shows the content +- `.collapsing` is added when the transition starts, and removed when it finishes + +These classes can be found in `_transitions.scss`. + +### Via data attributes + +Just add `data-bs-toggle="collapse"` and a `data-bs-target` to the element to automatically assign control of one or more collapsible elements. The `data-bs-target` attribute accepts a CSS selector to apply the collapse to. Be sure to add the class `collapse` to the collapsible element. If you'd like it to default open, add the additional class `show`. + +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. + +### Via JavaScript + +Enable manually with: + +```js +const collapseElementList = document.querySelectorAll('.collapse') +const collapseList = [...collapseElementList].map(collapseEl => new bootstrap.Collapse(collapseEl)) +``` + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< bs-table "table" >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +`parent` | selector, DOM element | `null` | If parent is provided, then all collapsible elements under the specified parent will be closed when this collapsible item is shown. (similar to traditional accordion behavior - this is dependent on the `card` class). The attribute has to be set on the target collapsible area. | +`toggle` | boolean | `true` | Toggles the collapsible element on invocation. | +{{< /bs-table >}} + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +Activates your content as a collapsible element. Accepts an optional options `object`. + +You can create a collapse instance with the constructor, for example: + +```js +const bsCollapse = new bootstrap.Collapse('#myCollapse', { + toggle: false +}) +``` + +{{< bs-table >}} +| Method | Description | +| --- | --- | +| `dispose` | Destroys an element's collapse. (Removes stored data on the DOM element) | +| `getInstance` | Static method which allows you to get the collapse instance associated to a DOM element, you can use it like this: `bootstrap.Collapse.getInstance(element)`. | +| `getOrCreateInstance` | Static method which returns a collapse instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `bootstrap.Collapse.getOrCreateInstance(element)`. | +| `hide` | Hides a collapsible element. **Returns to the caller before the collapsible element has actually been hidden** (e.g., before the `hidden.bs.collapse` event occurs). | +| `show` | Shows a collapsible element. **Returns to the caller before the collapsible element has actually been shown** (e.g., before the `shown.bs.collapse` event occurs). | +| `toggle` | Toggles a collapsible element to shown or hidden. **Returns to the caller before the collapsible element has actually been shown or hidden** (i.e. before the `shown.bs.collapse` or `hidden.bs.collapse` event occurs). | +{{< /bs-table >}} + +### Events + +Bootstrap's collapse class exposes a few events for hooking into collapse functionality. + +{{< bs-table >}} +| Event type | Description | +| --- | --- | +| `hide.bs.collapse` | This event is fired immediately when the `hide` method has been called. | +| `hidden.bs.collapse` | This event is fired when a collapse element has been hidden from the user (will wait for CSS transitions to complete). | +| `show.bs.collapse` | This event fires immediately when the `show` instance method is called. | +| `shown.bs.collapse` | This event is fired when a collapse element has been made visible to the user (will wait for CSS transitions to complete). | +{{< /bs-table >}} + +```js +const myCollapsible = document.getElementById('myCollapsible') +myCollapsible.addEventListener('hidden.bs.collapse', event => { + // do something... +}) +``` diff --git a/site/content/docs/5.2/components/dropdowns.md b/site/content/docs/5.2/components/dropdowns.md new file mode 100644 index 0000000..b589227 --- /dev/null +++ b/site/content/docs/5.2/components/dropdowns.md @@ -0,0 +1,1124 @@ +--- +layout: docs +title: Dropdowns +description: Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin. +group: components +toc: true +--- + +## Overview + +Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They're made interactive with the included Bootstrap dropdown JavaScript plugin. They're toggled by clicking, not by hovering; this is [an intentional design decision](https://markdotto.com/2012/02/27/bootstrap-explained-dropdowns/). + +Dropdowns are built on a third party library, [Popper](https://popper.js.org/), which provides dynamic positioning and viewport detection. Be sure to include [popper.min.js]({{< param "cdn.popper" >}}) before Bootstrap's JavaScript or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper. Popper isn't used to position dropdowns in navbars though as dynamic positioning isn't required. + +## Accessibility + +The [<abbr title="Web Accessibility Initiative">WAI</abbr> <abbr title="Accessible Rich Internet Applications">ARIA</abbr>](https://www.w3.org/TR/wai-aria/) standard defines an actual [`role="menu"` widget](https://www.w3.org/TR/wai-aria/#menu), but this is specific to application-like menus which trigger actions or functions. <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus can only contain menu items, checkbox menu items, radio button menu items, radio button groups, and sub-menus. + +Bootstrap's dropdowns, on the other hand, are designed to be generic and applicable to a variety of situations and markup structures. For instance, it is possible to create dropdowns that contain additional inputs and form controls, such as search fields or login forms. For this reason, Bootstrap does not expect (nor automatically add) any of the `role` and `aria-` attributes required for true <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus. Authors will have to include these more specific attributes themselves. + +However, Bootstrap does add built-in support for most standard keyboard menu interactions, such as the ability to move through individual `.dropdown-item` elements using the cursor keys and close the menu with the <kbd>ESC</kbd> key. + +## Examples + +Wrap the dropdown's toggle (your button or link) and the dropdown menu within `.dropdown`, or another element that declares `position: relative;`. Dropdowns can be triggered from `<a>` or `<button>` elements to better fit your potential needs. The examples shown here use semantic `<ul>` elements where appropriate, but custom markup is supported. + +### Single button + +Any single `.btn` can be turned into a dropdown toggle with some markup changes. Here's how you can put them to work with either `<button>` elements: + +{{< example >}} +<div class="dropdown"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown button + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> +</div> +{{< /example >}} + +And with `<a>` elements: + +{{< example >}} +<div class="dropdown"> + <a class="btn btn-secondary dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown link + </a> + + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> +</div> +{{< /example >}} + +The best part is you can do this with any button variant, too: + +<div class="bd-example"> + <div class="btn-group"> + <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">Primary</button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">Secondary</button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-success dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">Success</button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-info dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">Info</button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-warning dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">Warning</button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-danger dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">Danger</button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> +</div> + +```html +<!-- Example single danger button --> +<div class="btn-group"> + <button type="button" class="btn btn-danger dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Action + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> +</div> +``` + +### Split button + +Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of `.dropdown-toggle-split` for proper spacing around the dropdown caret. + +We use this extra class to reduce the horizontal `padding` on either side of the caret by 25% and remove the `margin-left` that's added for regular button dropdowns. Those extra changes keep the caret centered in the split button and provide a more appropriately sized hit area next to the main button. + +<div class="bd-example"> + <div class="btn-group"> + <button type="button" class="btn btn-primary">Primary</button> + <button type="button" class="btn btn-primary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-secondary">Secondary</button> + <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-success">Success</button> + <button type="button" class="btn btn-success dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-info">Info</button> + <button type="button" class="btn btn-info dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-warning">Warning</button> + <button type="button" class="btn btn-warning dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> + <div class="btn-group"> + <button type="button" class="btn btn-danger">Danger</button> + <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div><!-- /btn-group --> +</div> + +```html +<!-- Example split danger button --> +<div class="btn-group"> + <button type="button" class="btn btn-danger">Action</button> + <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> +</div> +``` + +## Sizing + +Button dropdowns work with buttons of all sizes, including default and split dropdown buttons. + +<div class="bd-example"> + <div class="btn-group"> + <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Large button + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> + <div class="btn-group"> + <button type="button" class="btn btn-lg btn-secondary">Large split button</button> + <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> +</div> + +```html +<!-- Large button groups (default and split) --> +<div class="btn-group"> + <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Large button + </button> + <ul class="dropdown-menu"> + ... + </ul> +</div> +<div class="btn-group"> + <button class="btn btn-secondary btn-lg" type="button"> + Large split button + </button> + <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + ... + </ul> +</div> +``` + +<div class="bd-example"> + <div class="btn-group"> + <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Small button + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> + <div class="btn-group"> + <button type="button" class="btn btn-sm btn-secondary">Small split button</button> + <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> +</div> + +```html +<div class="btn-group"> + <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Small button + </button> + <ul class="dropdown-menu"> + ... + </ul> +</div> +<div class="btn-group"> + <button class="btn btn-secondary btn-sm" type="button"> + Small split button + </button> + <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + ... + </ul> +</div> +``` + +## Dark dropdowns + +Opt into darker dropdowns to match a dark navbar or custom style by adding `.dropdown-menu-dark` onto an existing `.dropdown-menu`. No changes are required to the dropdown items. + +{{< example >}} +<div class="dropdown"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown button + </button> + <ul class="dropdown-menu dropdown-menu-dark"> + <li><a class="dropdown-item active" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> +</div> +{{< /example >}} + +And putting it to use in a navbar: + +{{< example >}} +<nav class="navbar navbar-expand-lg navbar-dark bg-dark"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNavDarkDropdown" aria-controls="navbarNavDarkDropdown" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarNavDarkDropdown"> + <ul class="navbar-nav"> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </a> + <ul class="dropdown-menu dropdown-menu-dark"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> + </li> + </ul> + </div> + </div> +</nav> +{{< /example >}} + +## Directions + +{{< callout info >}} +#### RTL +Directions are mirrored when using Bootstrap in RTL, meaning `.dropstart` will appear on the right side. +{{< /callout >}} + +### Centered + +Make the dropdown menu centered below the toggle with `.dropdown-center` on the parent element. + +{{< example >}} +<div class="dropdown-center"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Centered dropdown + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Action two</a></li> + <li><a class="dropdown-item" href="#">Action three</a></li> + </ul> +</div> +{{< /example >}} + +### Dropup + +Trigger dropdown menus above elements by adding `.dropup` to the parent element. + +<div class="bd-example"> + <div class="btn-group dropup"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropup + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> + <div class="btn-group dropup"> + <button type="button" class="btn btn-secondary"> + Split dropup + </button> + <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> +</div> + +```html +<!-- Default dropup button --> +<div class="btn-group dropup"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropup + </button> + <ul class="dropdown-menu"> + <!-- Dropdown menu links --> + </ul> +</div> + +<!-- Split dropup button --> +<div class="btn-group dropup"> + <button type="button" class="btn btn-secondary"> + Split dropup + </button> + <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <!-- Dropdown menu links --> + </ul> +</div> +``` + +### Dropup centered + +Make the dropup menu centered above the toggle with `.dropup-center` on the parent element. + +{{< example >}} +<div class="dropup-center dropup"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Centered dropup + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Action two</a></li> + <li><a class="dropdown-item" href="#">Action three</a></li> + </ul> +</div> +{{< /example >}} + +### Dropend + +Trigger dropdown menus at the right of the elements by adding `.dropend` to the parent element. + +<div class="bd-example"> + <div class="btn-group dropend"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropend + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> + <div class="btn-group dropend"> + <button type="button" class="btn btn-secondary"> + Split dropend + </button> + <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropend</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> +</div> + +```html +<!-- Default dropend button --> +<div class="btn-group dropend"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropend + </button> + <ul class="dropdown-menu"> + <!-- Dropdown menu links --> + </ul> +</div> + +<!-- Split dropend button --> +<div class="btn-group dropend"> + <button type="button" class="btn btn-secondary"> + Split dropend + </button> + <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropend</span> + </button> + <ul class="dropdown-menu"> + <!-- Dropdown menu links --> + </ul> +</div> +``` + +### Dropstart + +Trigger dropdown menus at the left of the elements by adding `.dropstart` to the parent element. + +<div class="bd-example"> + <div class="btn-group dropstart"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropstart + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> + <div class="btn-group dropstart"> + <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropstart</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + <button type="button" class="btn btn-secondary"> + Split dropstart + </button> + </div> +</div> + +```html +<!-- Default dropstart button --> +<div class="btn-group dropstart"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropstart + </button> + <ul class="dropdown-menu"> + <!-- Dropdown menu links --> + </ul> +</div> + +<!-- Split dropstart button --> +<div class="btn-group dropstart"> + <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropstart</span> + </button> + <ul class="dropdown-menu"> + <!-- Dropdown menu links --> + </ul> + <button type="button" class="btn btn-secondary"> + Split dropstart + </button> +</div> +``` + +## Menu items + +You can use `<a>` or `<button>` elements as dropdown items. + +{{< example >}} +<div class="dropdown"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </button> + <ul class="dropdown-menu"> + <li><button class="dropdown-item" type="button">Action</button></li> + <li><button class="dropdown-item" type="button">Another action</button></li> + <li><button class="dropdown-item" type="button">Something else here</button></li> + </ul> +</div> +{{< /example >}} + +You can also create non-interactive dropdown items with `.dropdown-item-text`. Feel free to style further with custom CSS or text utilities. + +{{< example >}} +<ul class="dropdown-menu"> + <li><span class="dropdown-item-text">Dropdown item text</span></li> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> +</ul> +{{< /example >}} + +### Active + +Add `.active` to items in the dropdown to **style them as active**. To convey the active state to assistive technologies, use the `aria-current` attribute — using the `page` value for the current page, or `true` for the current item in a set. + +{{< example >}} +<ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Regular link</a></li> + <li><a class="dropdown-item active" href="#" aria-current="true">Active link</a></li> + <li><a class="dropdown-item" href="#">Another link</a></li> +</ul> +{{< /example >}} + +### Disabled + +Add `.disabled` to items in the dropdown to **style them as disabled**. + +{{< example >}} +<ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Regular link</a></li> + <li><a class="dropdown-item disabled">Disabled link</a></li> + <li><a class="dropdown-item" href="#">Another link</a></li> +</ul> +{{< /example >}} + +## Menu alignment + +By default, a dropdown menu is automatically positioned 100% from the top and along the left side of its parent. You can change this with the directional `.drop*` classes, but you can also control them with additional modifier classes. + +Add `.dropdown-menu-end` to a `.dropdown-menu` to right align the dropdown menu. Directions are mirrored when using Bootstrap in RTL, meaning `.dropdown-menu-end` will appear on the left side. + +{{< callout info >}} +**Heads up!** Dropdowns are positioned thanks to Popper except when they are contained in a navbar. +{{< /callout >}} + +{{< example >}} +<div class="btn-group"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Right-aligned menu example + </button> + <ul class="dropdown-menu dropdown-menu-end"> + <li><button class="dropdown-item" type="button">Action</button></li> + <li><button class="dropdown-item" type="button">Another action</button></li> + <li><button class="dropdown-item" type="button">Something else here</button></li> + </ul> +</div> +{{< /example >}} + +### Responsive alignment + +If you want to use responsive alignment, disable dynamic positioning by adding the `data-bs-display="static"` attribute and use the responsive variation classes. + +To align **right** the dropdown menu with the given breakpoint or larger, add `.dropdown-menu{-sm|-md|-lg|-xl|-xxl}-end`. + +{{< example >}} +<div class="btn-group"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false"> + Left-aligned but right aligned when large screen + </button> + <ul class="dropdown-menu dropdown-menu-lg-end"> + <li><button class="dropdown-item" type="button">Action</button></li> + <li><button class="dropdown-item" type="button">Another action</button></li> + <li><button class="dropdown-item" type="button">Something else here</button></li> + </ul> +</div> +{{< /example >}} + +To align **left** the dropdown menu with the given breakpoint or larger, add `.dropdown-menu-end` and `.dropdown-menu{-sm|-md|-lg|-xl|-xxl}-start`. + +{{< example >}} +<div class="btn-group"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false"> + Right-aligned but left aligned when large screen + </button> + <ul class="dropdown-menu dropdown-menu-end dropdown-menu-lg-start"> + <li><button class="dropdown-item" type="button">Action</button></li> + <li><button class="dropdown-item" type="button">Another action</button></li> + <li><button class="dropdown-item" type="button">Something else here</button></li> + </ul> +</div> +{{< /example >}} + +Note that you don't need to add a `data-bs-display="static"` attribute to dropdown buttons in navbars, since Popper isn't used in navbars. + +### Alignment options + +Taking most of the options shown above, here's a small kitchen sink demo of various dropdown alignment options in one place. + +{{< example >}} +<div class="btn-group"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Right-aligned menu + </button> + <ul class="dropdown-menu dropdown-menu-end"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false"> + Left-aligned, right-aligned lg + </button> + <ul class="dropdown-menu dropdown-menu-lg-end"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false"> + Right-aligned, left-aligned lg + </button> + <ul class="dropdown-menu dropdown-menu-end dropdown-menu-lg-start"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group dropstart"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropstart + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group dropend"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropend + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group dropup"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false"> + Dropup + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> +{{< /example >}} + +## Menu content + +### Headers + +Add a header to label sections of actions in any dropdown menu. + +{{< example >}} +<ul class="dropdown-menu"> + <li><h6 class="dropdown-header">Dropdown header</h6></li> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> +</ul> +{{< /example >}} + +### Dividers + +Separate groups of related menu items with a divider. + +{{< example >}} +<ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> +</ul> +{{< /example >}} + +### Text + +Place any freeform text within a dropdown menu with text and use [spacing utilities]({{< docsref "/utilities/spacing" >}}). Note that you'll likely need additional sizing styles to constrain the menu width. + +{{< example >}} +<div class="dropdown-menu p-4 text-muted" style="max-width: 200px;"> + <p> + Some example text that's free-flowing within the dropdown menu. + </p> + <p class="mb-0"> + And this is more example text. + </p> +</div> +{{< /example >}} + +### Forms + +Put a form within a dropdown menu, or make it into a dropdown menu, and use [margin or padding utilities]({{< docsref "/utilities/spacing" >}}) to give it the negative space you require. + +{{< example >}} +<div class="dropdown-menu"> + <form class="px-4 py-3"> + <div class="mb-3"> + <label for="exampleDropdownFormEmail1" class="form-label">Email address</label> + <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com"> + </div> + <div class="mb-3"> + <label for="exampleDropdownFormPassword1" class="form-label">Password</label> + <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password"> + </div> + <div class="mb-3"> + <div class="form-check"> + <input type="checkbox" class="form-check-input" id="dropdownCheck"> + <label class="form-check-label" for="dropdownCheck"> + Remember me + </label> + </div> + </div> + <button type="submit" class="btn btn-primary">Sign in</button> + </form> + <div class="dropdown-divider"></div> + <a class="dropdown-item" href="#">New around here? Sign up</a> + <a class="dropdown-item" href="#">Forgot password?</a> +</div> +{{< /example >}} + +{{< example >}} +<div class="dropdown"> + <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false" data-bs-auto-close="outside"> + Dropdown form + </button> + <form class="dropdown-menu p-4"> + <div class="mb-3"> + <label for="exampleDropdownFormEmail2" class="form-label">Email address</label> + <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="email@example.com"> + </div> + <div class="mb-3"> + <label for="exampleDropdownFormPassword2" class="form-label">Password</label> + <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password"> + </div> + <div class="mb-3"> + <div class="form-check"> + <input type="checkbox" class="form-check-input" id="dropdownCheck2"> + <label class="form-check-label" for="dropdownCheck2"> + Remember me + </label> + </div> + </div> + <button type="submit" class="btn btn-primary">Sign in</button> + </form> +</div> +{{< /example >}} + +## Dropdown options + +Use `data-bs-offset` or `data-bs-reference` to change the location of the dropdown. + +{{< example >}} +<div class="d-flex"> + <div class="dropdown me-1"> + <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false" data-bs-offset="10,20"> + Offset + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> + </div> + <div class="btn-group"> + <button type="button" class="btn btn-secondary">Reference</button> + <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false" data-bs-reference="parent"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </div> +</div> +{{< /example >}} + +### Auto close behavior + +By default, the dropdown menu is closed when clicking inside or outside the dropdown menu. You can use the `autoClose` option to change this behavior of the dropdown. + +{{< example >}} +<div class="btn-group"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="true" aria-expanded="false"> + Default dropdown + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="inside" aria-expanded="false"> + Clickable outside + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="outside" aria-expanded="false"> + Clickable inside + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> + +<div class="btn-group"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="false" aria-expanded="false"> + Manual close + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + <li><a class="dropdown-item" href="#">Menu item</a></li> + </ul> +</div> +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, dropdowns now use local CSS variables on `.dropdown-menu` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="dropdown-css-vars" file="scss/_dropdown.scss" >}} + +Customization through CSS variables can be seen on the `.dropdown-menu-dark` class where we override specific values without adding duplicate CSS selectors. + +{{< scss-docs name="dropdown-dark-css-vars" file="scss/_dropdown.scss" >}} + +### Sass variables + +Variables for all dropdowns: + +{{< scss-docs name="dropdown-variables" file="scss/_variables.scss" >}} + +Variables for the [dark dropdown](#dark-dropdowns): + +{{< scss-docs name="dropdown-dark-variables" file="scss/_variables.scss" >}} + +Variables for the CSS-based carets that indicate a dropdown's interactivity: + +{{< scss-docs name="caret-variables" file="scss/_variables.scss" >}} + +### Mixins + +Mixins are used to generate the CSS-based carets and can be found in `scss/mixins/_caret.scss`. + +{{< scss-docs name="caret-mixins" file="scss/mixins/_caret.scss" >}} + +## Usage + +Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the `.show` class on the parent `.dropdown-menu`. The `data-bs-toggle="dropdown"` attribute is relied on for closing dropdown menus at an application level, so it's a good idea to always use it. + +{{< callout info >}} +On touch-enabled devices, opening a dropdown adds empty `mouseover` handlers to the immediate children of the `<body>` element. This admittedly ugly hack is necessary to work around a [quirk in iOS' event delegation](https://www.quirksmode.org/blog/archives/2014/02/mouse_event_bub.html), which would otherwise prevent a tap anywhere outside of the dropdown from triggering the code that closes the dropdown. Once the dropdown is closed, these additional empty `mouseover` handlers are removed. +{{< /callout >}} + +### Via data attributes + +Add `data-bs-toggle="dropdown"` to a link or button to toggle a dropdown. + +```html +<div class="dropdown"> + <button type="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown trigger + </button> + <ul class="dropdown-menu"> + ... + </ul> +</div> +``` + +### Via JavaScript + +Call the dropdowns via JavaScript: + +```js +const dropdownElementList = document.querySelectorAll('.dropdown-toggle') +const dropdownList = [...dropdownElementList].map(dropdownToggleEl => new bootstrap.Dropdown(dropdownToggleEl)) +``` + +{{< callout info >}} +##### `data-bs-toggle="dropdown"` still required + +Regardless of whether you call your dropdown via JavaScript or instead use the data-api, `data-bs-toggle="dropdown"` is always required to be present on the dropdown's trigger element. +{{< /callout >}} + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< bs-table "table" >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `autoClose` | boolean, string | `true` | Configure the auto close behavior of the dropdown: <ul class="my-2"><li>`true` - the dropdown will be closed by clicking outside or inside the dropdown menu.</li><li>`false` - the dropdown will be closed by clicking the toggle button and manually calling `hide` or `toggle` method. (Also will not be closed by pressing <kbd>esc</kbd> key)</li><li>`'inside'` - the dropdown will be closed (only) by clicking inside the dropdown menu.</li> <li>`'outside'` - the dropdown will be closed (only) by clicking outside the dropdown menu.</li></ul> Note: the dropdown can always be closed with the <kbd>ESC</kbd> key. | +| `boundary` | string, element | `'clippingParents'` | Overflow constraint boundary of the dropdown menu (applies only to Popper's preventOverflow modifier). By default it's `clippingParents` and can accept an HTMLElement reference (via JavaScript only). For more information refer to Popper's [detectOverflow docs](https://popper.js.org/docs/v2/utils/detect-overflow/#boundary). | +| `display` | string | `'dynamic'` | By default, we use Popper for dynamic positioning. Disable this with `static`. | +| `offset` | array, string, function | `[0, 2]` | Offset of the dropdown relative to its target. You can pass a string in data attributes with comma separated values like: `data-bs-offset="10,20"`. When a function is used to determine the offset, it is called with an object containing the popper placement, the reference, and popper rects as its first argument. The triggering element DOM node is passed as the second argument. The function must return an array with two numbers: [skidding](https://popper.js.org/docs/v2/modifiers/offset/#skidding-1), [distance](https://popper.js.org/docs/v2/modifiers/offset/#distance-1). For more information refer to Popper's [offset docs](https://popper.js.org/docs/v2/modifiers/offset/#options). | +| `popperConfig` | null, object, function | `null` | To change Bootstrap's default Popper config, see [Popper's configuration](https://popper.js.org/docs/v2/constructors/#options). When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper. | +| `reference` | string, element, object | `'toggle'` | Reference element of the dropdown menu. Accepts the values of `'toggle'`, `'parent'`, an HTMLElement reference or an object providing `getBoundingClientRect`. For more information refer to Popper's [constructor docs](https://popper.js.org/docs/v2/constructors/#createpopper) and [virtual element docs](https://popper.js.org/docs/v2/virtual-elements/). | +{{< /bs-table >}} + +#### Using function with `popperConfig` + +```js +const dropdown = new bootstrap.Dropdown(element, { + popperConfig(defaultBsPopperConfig) { + // const newPopperConfig = {...} + // use defaultBsPopperConfig if needed... + // return newPopperConfig + } +}) +``` + +### Methods + +{{< bs-table >}} +| Method | Description | +| --- | --- | +| `dispose` | Destroys an element's dropdown. (Removes stored data on the DOM element) | +| `getInstance` | Static method which allows you to get the dropdown instance associated to a DOM element, you can use it like this: `bootstrap.Dropdown.getInstance(element)`. | +| `getOrCreateInstance` | Static method which returns a dropdown instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `bootstrap.Dropdown.getOrCreateInstance(element)`. | +| `hide` | Hides the dropdown menu of a given navbar or tabbed navigation. | +| `show` | Shows the dropdown menu of a given navbar or tabbed navigation. | +| `toggle` | Toggles the dropdown menu of a given navbar or tabbed navigation. | +| `update` | Updates the position of an element's dropdown. | +{{< /bs-table >}} + +### Events + +All dropdown events are fired at the toggling element and then bubbled up. So you can also add event listeners on the `.dropdown-menu`'s parent element. `hide.bs.dropdown` and `hidden.bs.dropdown` events have a `clickEvent` property (only when the original Event type is `click`) that contains an Event Object for the click event. + +{{< bs-table >}} +| Event type | Description | +| --- | --- | +| `hide.bs.dropdown` | Fires immediately when the `hide` instance method has been called. | +| `hidden.bs.dropdown` | Fired when the dropdown has finished being hidden from the user and CSS transitions have completed. | +| `show.bs.dropdown` | Fires immediately when the `show` instance method is called. | +| `shown.bs.dropdown` | Fired when the dropdown has been made visible to the user and CSS transitions have completed. | +{{< /bs-table >}} + +```js +const myDropdown = document.getElementById('myDropdown') +myDropdown.addEventListener('show.bs.dropdown', event => { + // do something... +}) +``` diff --git a/site/content/docs/5.2/components/list-group.md b/site/content/docs/5.2/components/list-group.md new file mode 100644 index 0000000..7804c74 --- /dev/null +++ b/site/content/docs/5.2/components/list-group.md @@ -0,0 +1,494 @@ +--- +layout: docs +title: List group +description: List groups are a flexible and powerful component for displaying a series of content. Modify and extend them to support just about any content within. +group: components +toc: true +--- + +## Basic example + +The most basic list group is an unordered list with list items and the proper classes. Build upon it with the options that follow, or with your own CSS as needed. + +{{< example >}} +<ul class="list-group"> + <li class="list-group-item">An item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> + <li class="list-group-item">A fourth item</li> + <li class="list-group-item">And a fifth one</li> +</ul> +{{< /example >}} + +## Active items + +Add `.active` to a `.list-group-item` to indicate the current active selection. + +{{< example >}} +<ul class="list-group"> + <li class="list-group-item active" aria-current="true">An active item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> + <li class="list-group-item">A fourth item</li> + <li class="list-group-item">And a fifth one</li> +</ul> +{{< /example >}} + +## Disabled items + +Add `.disabled` to a `.list-group-item` to make it _appear_ disabled. Note that some elements with `.disabled` will also require custom JavaScript to fully disable their click events (e.g., links). + +{{< example >}} +<ul class="list-group"> + <li class="list-group-item disabled" aria-disabled="true">A disabled item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> + <li class="list-group-item">A fourth item</li> + <li class="list-group-item">And a fifth one</li> +</ul> +{{< /example >}} + +## Links and buttons + +Use `<a>`s or `<button>`s to create _actionable_ list group items with hover, disabled, and active states by adding `.list-group-item-action`. We separate these pseudo-classes to ensure list groups made of non-interactive elements (like `<li>`s or `<div>`s) don't provide a click or tap affordance. + +Be sure to **not use the standard `.btn` classes here**. + +{{< example >}} +<div class="list-group"> + <a href="#" class="list-group-item list-group-item-action active" aria-current="true"> + The current link item + </a> + <a href="#" class="list-group-item list-group-item-action">A second link item</a> + <a href="#" class="list-group-item list-group-item-action">A third link item</a> + <a href="#" class="list-group-item list-group-item-action">A fourth link item</a> + <a class="list-group-item list-group-item-action disabled">A disabled link item</a> +</div> +{{< /example >}} + +With `<button>`s, you can also make use of the `disabled` attribute instead of the `.disabled` class. Sadly, `<a>`s don't support the disabled attribute. + +{{< example >}} +<div class="list-group"> + <button type="button" class="list-group-item list-group-item-action active" aria-current="true"> + The current button + </button> + <button type="button" class="list-group-item list-group-item-action">A second button item</button> + <button type="button" class="list-group-item list-group-item-action">A third button item</button> + <button type="button" class="list-group-item list-group-item-action">A fourth button item</button> + <button type="button" class="list-group-item list-group-item-action" disabled>A disabled button item</button> +</div> +{{< /example >}} + +## Flush + +Add `.list-group-flush` to remove some borders and rounded corners to render list group items edge-to-edge in a parent container (e.g., cards). + +{{< example >}} +<ul class="list-group list-group-flush"> + <li class="list-group-item">An item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> + <li class="list-group-item">A fourth item</li> + <li class="list-group-item">And a fifth one</li> +</ul> +{{< /example >}} + +## Numbered + +Add the `.list-group-numbered` modifier class (and optionally use an `<ol>` element) to opt into numbered list group items. Numbers are generated via CSS (as opposed to a `<ol>`s default browser styling) for better placement inside list group items and to allow for better customization. + +Numbers are generated by `counter-reset` on the `<ol>`, and then styled and placed with a `::before` pseudo-element on the `<li>` with `counter-increment` and `content`. + +{{< example >}} +<ol class="list-group list-group-numbered"> + <li class="list-group-item">A list item</li> + <li class="list-group-item">A list item</li> + <li class="list-group-item">A list item</li> +</ol> +{{< /example >}} + +These work great with custom content as well. + +{{< example >}} +<ol class="list-group list-group-numbered"> + <li class="list-group-item d-flex justify-content-between align-items-start"> + <div class="ms-2 me-auto"> + <div class="fw-bold">Subheading</div> + Content for list item + </div> + <span class="badge bg-primary rounded-pill">14</span> + </li> + <li class="list-group-item d-flex justify-content-between align-items-start"> + <div class="ms-2 me-auto"> + <div class="fw-bold">Subheading</div> + Content for list item + </div> + <span class="badge bg-primary rounded-pill">14</span> + </li> + <li class="list-group-item d-flex justify-content-between align-items-start"> + <div class="ms-2 me-auto"> + <div class="fw-bold">Subheading</div> + Content for list item + </div> + <span class="badge bg-primary rounded-pill">14</span> + </li> +</ol> +{{< /example >}} + +## Horizontal + +Add `.list-group-horizontal` to change the layout of list group items from vertical to horizontal across all breakpoints. Alternatively, choose a responsive variant `.list-group-horizontal-{sm|md|lg|xl|xxl}` to make a list group horizontal starting at that breakpoint's `min-width`. Currently **horizontal list groups cannot be combined with flush list groups.** + +**ProTip:** Want equal-width list group items when horizontal? Add `.flex-fill` to each list group item. + +{{< example >}} +{{< list-group.inline >}} +{{- range $.Site.Data.breakpoints }} +<ul class="list-group list-group-horizontal{{ .abbr }}"> + <li class="list-group-item">An item</li> + <li class="list-group-item">A second item</li> + <li class="list-group-item">A third item</li> +</ul> +{{- end -}} +{{< /list-group.inline >}} +{{< /example >}} + +## Contextual classes + +Use contextual classes to style list items with a stateful background and color. + +{{< example >}} +<ul class="list-group"> + <li class="list-group-item">A simple default list group item</li> +{{< list.inline >}} +{{- range (index $.Site.Data "theme-colors") }} + <li class="list-group-item list-group-item-{{ .name }}">A simple {{ .name }} list group item</li> +{{- end -}} +{{< /list.inline >}} +</ul> +{{< /example >}} + +Contextual classes also work with `.list-group-item-action`. Note the addition of the hover styles here not present in the previous example. Also supported is the `.active` state; apply it to indicate an active selection on a contextual list group item. + +{{< example >}} +<div class="list-group"> + <a href="#" class="list-group-item list-group-item-action">A simple default list group item</a> +{{< list.inline >}} +{{- range (index $.Site.Data "theme-colors") }} + <a href="#" class="list-group-item list-group-item-action list-group-item-{{ .name }}">A simple {{ .name }} list group item</a> +{{- end -}} +{{< /list.inline >}} +</div> +{{< /example >}} + +{{< callout info >}} +{{< partial "callout-warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## With badges + +Add badges to any list group item to show unread counts, activity, and more with the help of some [utilities]({{< docsref "/utilities/flex" >}}). + +{{< example >}} +<ul class="list-group"> + <li class="list-group-item d-flex justify-content-between align-items-center"> + A list item + <span class="badge bg-primary rounded-pill">14</span> + </li> + <li class="list-group-item d-flex justify-content-between align-items-center"> + A second list item + <span class="badge bg-primary rounded-pill">2</span> + </li> + <li class="list-group-item d-flex justify-content-between align-items-center"> + A third list item + <span class="badge bg-primary rounded-pill">1</span> + </li> +</ul> +{{< /example >}} + +## Custom content + +Add nearly any HTML within, even for linked list groups like the one below, with the help of [flexbox utilities]({{< docsref "/utilities/flex" >}}). + +{{< example >}} +<div class="list-group"> + <a href="#" class="list-group-item list-group-item-action active" aria-current="true"> + <div class="d-flex w-100 justify-content-between"> + <h5 class="mb-1">List group item heading</h5> + <small>3 days ago</small> + </div> + <p class="mb-1">Some placeholder content in a paragraph.</p> + <small>And some small print.</small> + </a> + <a href="#" class="list-group-item list-group-item-action"> + <div class="d-flex w-100 justify-content-between"> + <h5 class="mb-1">List group item heading</h5> + <small class="text-muted">3 days ago</small> + </div> + <p class="mb-1">Some placeholder content in a paragraph.</p> + <small class="text-muted">And some muted small print.</small> + </a> + <a href="#" class="list-group-item list-group-item-action"> + <div class="d-flex w-100 justify-content-between"> + <h5 class="mb-1">List group item heading</h5> + <small class="text-muted">3 days ago</small> + </div> + <p class="mb-1">Some placeholder content in a paragraph.</p> + <small class="text-muted">And some muted small print.</small> + </a> +</div> +{{< /example >}} + +## Checkboxes and radios + +Place Bootstrap's checkboxes and radios within list group items and customize as needed. You can use them without `<label>`s, but please remember to include an `aria-label` attribute and value for accessibility. + +{{< example >}} +<ul class="list-group"> + <li class="list-group-item"> + <input class="form-check-input me-1" type="checkbox" value="" id="firstCheckbox"> + <label class="form-check-label" for="firstCheckbox">First checkbox</label> + </li> + <li class="list-group-item"> + <input class="form-check-input me-1" type="checkbox" value="" id="secondCheckbox"> + <label class="form-check-label" for="secondCheckbox">Second checkbox</label> + </li> + <li class="list-group-item"> + <input class="form-check-input me-1" type="checkbox" value="" id="thirdCheckbox"> + <label class="form-check-label" for="thirdCheckbox">Third checkbox</label> + </li> +</ul> +{{< /example >}} + +{{< example >}} +<ul class="list-group"> + <li class="list-group-item"> + <input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="firstRadio" checked> + <label class="form-check-label" for="firstRadio">First radio</label> + </li> + <li class="list-group-item"> + <input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="secondRadio"> + <label class="form-check-label" for="secondRadio">Second radio</label> + </li> + <li class="list-group-item"> + <input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="thirdRadio"> + <label class="form-check-label" for="thirdRadio">Third radio</label> + </li> +</ul> +{{< /example >}} + +You can use `.stretched-link` on `<label>`s to make the whole list group item clickable. + +{{< example >}} +<ul class="list-group"> + <li class="list-group-item"> + <input class="form-check-input me-1" type="checkbox" value="" id="firstCheckboxStretched"> + <label class="form-check-label stretched-link" for="firstCheckboxStretched">First checkbox</label> + </li> + <li class="list-group-item"> + <input class="form-check-input me-1" type="checkbox" value="" id="secondCheckboxStretched"> + <label class="form-check-label stretched-link" for="secondCheckboxStretched">Second checkbox</label> + </li> + <li class="list-group-item"> + <input class="form-check-input me-1" type="checkbox" value="" id="thirdCheckboxStretched"> + <label class="form-check-label stretched-link" for="thirdCheckboxStretched">Third checkbox</label> + </li> +</ul> +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, list groups now use local CSS variables on `.list-group` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="list-group-css-vars" file="scss/_list-group.scss" >}} + +### Sass variables + +{{< scss-docs name="list-group-variables" file="scss/_variables.scss" >}} + +### Mixins + +Used in combination with `$theme-colors` to generate the [contextual variant classes](#contextual-classes) for `.list-group-item`s. + +{{< scss-docs name="list-group-mixin" file="scss/mixins/_list-group.scss" >}} + +### Loop + +Loop that generates the modifier classes with the `list-group-item-variant()` mixin. + +{{< scss-docs name="list-group-modifiers" file="scss/_list-group.scss" >}} + +## JavaScript behavior + +Use the tab JavaScript plugin—include it individually or through the compiled `bootstrap.js` file—to extend our list group to create tabbable panes of local content. + +<div class="bd-example" role="tabpanel"> + <div class="row"> + <div class="col-4"> + <div class="list-group" id="list-tab" role="tablist"> + <a class="list-group-item list-group-item-action active" id="list-home-list" data-bs-toggle="tab" href="#list-home" role="tab" aria-controls="list-home">Home</a> + <a class="list-group-item list-group-item-action" id="list-profile-list" data-bs-toggle="tab" href="#list-profile" role="tab" aria-controls="list-profile">Profile</a> + <a class="list-group-item list-group-item-action" id="list-messages-list" data-bs-toggle="tab" href="#list-messages" role="tab" aria-controls="list-messages">Messages</a> + <a class="list-group-item list-group-item-action" id="list-settings-list" data-bs-toggle="tab" href="#list-settings" role="tab" aria-controls="list-settings">Settings</a> + </div> + </div> + <div class="col-8"> + <div class="tab-content" id="nav-tabContent"> + <div class="tab-pane fade show active" id="list-home" role="tabpanel" aria-labelledby="list-home-list"> + <p>Some placeholder content in a paragraph relating to "Home". And some more content, used here just to pad out and fill this tab panel. In production, you would obviously have more real content here. And not just text. It could be anything, really. Text, images, forms.</p> + </div> + <div class="tab-pane fade" id="list-profile" role="tabpanel" aria-labelledby="list-profile-list"> + <p>Some placeholder content in a paragraph relating to "Profile". And some more content, used here just to pad out and fill this tab panel. In production, you would obviously have more real content here. And not just text. It could be anything, really. Text, images, forms.</p> + </div> + <div class="tab-pane fade" id="list-messages" role="tabpanel" aria-labelledby="list-messages-list"> + <p>Some placeholder content in a paragraph relating to "Messages". And some more content, used here just to pad out and fill this tab panel. In production, you would obviously have more real content here. And not just text. It could be anything, really. Text, images, forms.</p> + </div> + <div class="tab-pane fade" id="list-settings" role="tabpanel" aria-labelledby="list-settings-list"> + <p>Some placeholder content in a paragraph relating to "Settings". And some more content, used here just to pad out and fill this tab panel. In production, you would obviously have more real content here. And not just text. It could be anything, really. Text, images, forms.</p> + </div> + </div> + </div> + </div> +</div> + +```html +<div class="row"> + <div class="col-4"> + <div class="list-group" id="list-tab" role="tablist"> + <a class="list-group-item list-group-item-action active" id="list-home-list" data-bs-toggle="list" href="#list-home" role="tab" aria-controls="list-home">Home</a> + <a class="list-group-item list-group-item-action" id="list-profile-list" data-bs-toggle="list" href="#list-profile" role="tab" aria-controls="list-profile">Profile</a> + <a class="list-group-item list-group-item-action" id="list-messages-list" data-bs-toggle="list" href="#list-messages" role="tab" aria-controls="list-messages">Messages</a> + <a class="list-group-item list-group-item-action" id="list-settings-list" data-bs-toggle="list" href="#list-settings" role="tab" aria-controls="list-settings">Settings</a> + </div> + </div> + <div class="col-8"> + <div class="tab-content" id="nav-tabContent"> + <div class="tab-pane fade show active" id="list-home" role="tabpanel" aria-labelledby="list-home-list">...</div> + <div class="tab-pane fade" id="list-profile" role="tabpanel" aria-labelledby="list-profile-list">...</div> + <div class="tab-pane fade" id="list-messages" role="tabpanel" aria-labelledby="list-messages-list">...</div> + <div class="tab-pane fade" id="list-settings" role="tabpanel" aria-labelledby="list-settings-list">...</div> + </div> + </div> +</div> +``` + +### Using data attributes + +You can activate a list group navigation without writing any JavaScript by simply specifying `data-bs-toggle="list"` or on an element. Use these data attributes on `.list-group-item`. + +```html +<div role="tabpanel"> + <!-- List group --> + <div class="list-group" id="myList" role="tablist"> + <a class="list-group-item list-group-item-action active" data-bs-toggle="list" href="#home" role="tab">Home</a> + <a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#profile" role="tab">Profile</a> + <a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#messages" role="tab">Messages</a> + <a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#settings" role="tab">Settings</a> + </div> + + <!-- Tab panes --> + <div class="tab-content"> + <div class="tab-pane active" id="home" role="tabpanel">...</div> + <div class="tab-pane" id="profile" role="tabpanel">...</div> + <div class="tab-pane" id="messages" role="tabpanel">...</div> + <div class="tab-pane" id="settings" role="tabpanel">...</div> + </div> +</div> +``` + +### Via JavaScript + +Enable tabbable list item via JavaScript (each list item needs to be activated individually): + +```js +const triggerTabList = document.querySelectorAll('#myTab a') +triggerTabList.forEach(triggerEl => { + const tabTrigger = new bootstrap.Tab(triggerEl) + + triggerEl.addEventListener('click', event => { + event.preventDefault() + tabTrigger.show() + }) +}) +``` + +You can activate individual list item in several ways: + +```js +const triggerEl = document.querySelector('#myTab a[href="#profile"]') +bootstrap.Tab.getInstance(triggerEl).show() // Select tab by name + +const triggerFirstTabEl = document.querySelector('#myTab li:first-child a') +bootstrap.Tab.getInstance(triggerFirstTabEl).show() // Select first tab +``` + +### Fade effect + +To make tabs panel fade in, add `.fade` to each `.tab-pane`. The first tab pane must also have `.show` to make the initial content visible. + +```html +<div class="tab-content"> + <div class="tab-pane fade show active" id="home" role="tabpanel">...</div> + <div class="tab-pane fade" id="profile" role="tabpanel">...</div> + <div class="tab-pane fade" id="messages" role="tabpanel">...</div> + <div class="tab-pane fade" id="settings" role="tabpanel">...</div> +</div> +``` + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +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') +``` + +{{< bs-table >}} +| 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). | +{{< /bs-table >}} + +### 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. + +{{< bs-table >}} +| 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. | +{{< /bs-table >}} + +```js +const tabElms = document.querySelectorAll('a[data-bs-toggle="list"]') +tabElms.forEach(tabElm => { + tabElm.addEventListener('shown.bs.tab', event => { + event.target // newly activated tab + event.relatedTarget // previous active tab + }) +}) +``` diff --git a/site/content/docs/5.2/components/modal.md b/site/content/docs/5.2/components/modal.md new file mode 100644 index 0000000..ed31b73 --- /dev/null +++ b/site/content/docs/5.2/components/modal.md @@ -0,0 +1,888 @@ +--- +layout: docs +title: Modal +description: Use Bootstrap's JavaScript modal plugin to add dialogs to your site for lightboxes, user notifications, or completely custom content. +group: components +toc: true +--- + +## How it works + +Before getting started with Bootstrap's modal component, be sure to read the following as our menu options have recently changed. + +- Modals are built with HTML, CSS, and JavaScript. They're positioned over everything else in the document and remove scroll from the `<body>` so that modal content scrolls instead. +- Clicking on the modal "backdrop" will automatically close the modal. +- Bootstrap only supports one modal window at a time. Nested modals aren't supported as we believe them to be poor user experiences. +- Modals use `position: fixed`, which can sometimes be a bit particular about its rendering. Whenever possible, place your modal HTML in a top-level position to avoid potential interference from other elements. You'll likely run into issues when nesting a `.modal` within another fixed element. +- Once again, due to `position: fixed`, there are some caveats with using modals on mobile devices. [See our browser support docs]({{< docsref "/getting-started/browsers-devices#modals-and-dropdowns-on-mobile" >}}) for details. +- Due to how HTML5 defines its semantics, [the `autofocus` HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-autofocus) has no effect in Bootstrap modals. To achieve the same effect, use some custom JavaScript: + +```js +const myModal = document.getElementById('myModal') +const myInput = document.getElementById('myInput') + +myModal.addEventListener('shown.bs.modal', () => { + myInput.focus() +}) +``` + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +Keep reading for demos and usage guidelines. + +## Examples + +### Modal components + +Below is a _static_ modal example (meaning its `position` and `display` have been overridden). Included are the modal header, modal body (required for `padding`), and modal footer (optional). We ask that you include modal headers with dismiss actions whenever possible, or provide another explicit dismiss action. + +<div class="bd-example bg-light"> + <div class="modal position-static d-block" tabindex="-1"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h5 class="modal-title">Modal title</h5> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <p>Modal body text goes here.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> + </div> +</div> + +```html +<div class="modal" tabindex="-1"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h5 class="modal-title">Modal title</h5> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <p>Modal body text goes here.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> +``` + +{{< callout info >}} +In the above static example, we use `<h5>`, to avoid issues with the heading hierarchy in the documentation page. Structurally, however, a modal dialog represents its own separate document/context, so the `.modal-title` should ideally be an `<h1>`. If necessary, you can use the [font size utilities]({{< docsref "/utilities/text#font-size" >}}) to control the heading's appearance. All the following live examples use this approach. +{{< /callout >}} + +### Live demo + +Toggle a working modal demo by clicking the button below. It will slide down and fade in from the top of the page. + +<div class="modal fade" id="exampleModalLive" tabindex="-1" aria-labelledby="exampleModalLiveLabel" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalLiveLabel">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <p>Woo-hoo, you're reading this text in a modal!</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> + +<div class="bd-example"> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalLive"> + Launch demo modal + </button> +</div> + +```html +<!-- Button trigger modal --> +<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal"> + Launch demo modal +</button> + +<!-- Modal --> +<div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalLabel">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> +``` + +### Static backdrop + +When backdrop is set to static, the modal will not close when clicking outside of it. Click the button below to try it. + +<div class="modal fade" id="staticBackdropLive" data-bs-backdrop="static" data-bs-keyboard="false" tabindex="-1" aria-labelledby="staticBackdropLiveLabel" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="staticBackdropLiveLabel">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <p>I will not close if you click outside of me. Don't even try to press escape key.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Understood</button> + </div> + </div> + </div> +</div> + +<div class="bd-example"> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#staticBackdropLive"> + Launch static backdrop modal + </button> +</div> + +```html +<!-- Button trigger modal --> +<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#staticBackdrop"> + Launch static backdrop modal +</button> + +<!-- Modal --> +<div class="modal fade" id="staticBackdrop" data-bs-backdrop="static" data-bs-keyboard="false" tabindex="-1" aria-labelledby="staticBackdropLabel" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="staticBackdropLabel">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Understood</button> + </div> + </div> + </div> +</div> +``` + +### Scrolling long content + +When modals become too long for the user's viewport or device, they scroll independent of the page itself. Try the demo below to see what we mean. + +<div class="modal fade" id="exampleModalLong" tabindex="-1" aria-labelledby="exampleModalLongTitle" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalLongTitle">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body" style="min-height: 1500px"> + <p>This is some placeholder content to show the scrolling behavior for modals. Instead of repeating the text the modal, we use an inline style set a minimum height, thereby extending the length of the overall modal and demonstrating the overflow scrolling. When content becomes longer than the height of the viewport, scrolling will move the modal as needed.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> + +<div class="bd-example"> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalLong"> + Launch demo modal + </button> +</div> + +You can also create a scrollable modal that allows scroll the modal body by adding `.modal-dialog-scrollable` to `.modal-dialog`. + +<div class="modal fade" id="exampleModalScrollable" tabindex="-1" aria-labelledby="exampleModalScrollableTitle" aria-hidden="true"> + <div class="modal-dialog modal-dialog-scrollable"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalScrollableTitle">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <p>This is some placeholder content to show the scrolling behavior for modals. We use repeated line breaks to demonstrate how content can exceed minimum inner height, thereby showing inner scrolling. When content becomes longer than the predefined max-height of modal, content will be cropped and scrollable within the modal.</p> + <br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br> + <p>This content should appear at the bottom after you scroll.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> + +<div class="bd-example"> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalScrollable"> + Launch demo modal + </button> +</div> + +```html +<!-- Scrollable modal --> +<div class="modal-dialog modal-dialog-scrollable"> + ... +</div> +``` + +### Vertically centered + +Add `.modal-dialog-centered` to `.modal-dialog` to vertically center the modal. + +<div class="modal fade" id="exampleModalCenter" tabindex="-1" aria-labelledby="exampleModalCenterTitle" aria-hidden="true"> + <div class="modal-dialog modal-dialog-centered"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalCenterTitle">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <p>This is a vertically centered modal.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> + +<div class="modal fade" id="exampleModalCenteredScrollable" tabindex="-1" aria-labelledby="exampleModalCenteredScrollableTitle" aria-hidden="true"> + <div class="modal-dialog modal-dialog-centered modal-dialog-scrollable"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalCenteredScrollableTitle">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <p>This is some placeholder content to show a vertically centered modal. We've added some extra copy here to show how vertically centering the modal works when combined with scrollable modals. We also use some repeated line breaks to quickly extend the height of the content, thereby triggering the scrolling. When content becomes longer than the predefined max-height of modal, content will be cropped and scrollable within the modal.</p> + <br><br><br><br><br><br><br><br><br><br> + <p>Just like that.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> + +<div class="bd-example"> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalCenter"> + Vertically centered modal + </button> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalCenteredScrollable"> + Vertically centered scrollable modal + </button> +</div> + +```html +<!-- Vertically centered modal --> +<div class="modal-dialog modal-dialog-centered"> + ... +</div> + +<!-- Vertically centered scrollable modal --> +<div class="modal-dialog modal-dialog-centered modal-dialog-scrollable"> + ... +</div> +``` + +### Tooltips and popovers + +[Tooltips]({{< docsref "/components/tooltips" >}}) and [popovers]({{< docsref "/components/popovers" >}}) can be placed within modals as needed. When modals are closed, any tooltips and popovers within are also automatically dismissed. + +<div class="modal fade" id="exampleModalPopovers" tabindex="-1" aria-labelledby="exampleModalPopoversLabel" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalPopoversLabel">Modal title</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <h2 class="fs-5">Popover in a modal</h2> + <p>This <a href="#" role="button" class="btn btn-secondary" data-bs-toggle="popover" title="Popover title" data-bs-content="Popover body content is set in this attribute." data-bs-container="#exampleModalPopovers">button</a> triggers a popover on click.</p> + <hr> + <h2 class="fs-5">Tooltips in a modal</h2> + <p><a href="#" data-bs-toggle="tooltip" title="Tooltip" data-bs-container="#exampleModalPopovers">This link</a> and <a href="#" data-bs-toggle="tooltip" title="Tooltip" data-bs-container="#exampleModalPopovers">that link</a> have tooltips on hover.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> + +<div class="bd-example"> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalPopovers"> + Launch demo modal + </button> +</div> + +```html +<div class="modal-body"> + <h2 class="fs-5">Popover in a modal</h2> + <p>This <a href="#" role="button" class="btn btn-secondary" data-bs-toggle="popover" title="Popover title" data-bs-content="Popover body content is set in this attribute.">button</a> triggers a popover on click.</p> + <hr> + <h2 class="fs-5">Tooltips in a modal</h2> + <p><a href="#" data-bs-toggle="tooltip" title="Tooltip">This link</a> and <a href="#" data-bs-toggle="tooltip" title="Tooltip">that link</a> have tooltips on hover.</p> +</div> +``` + +### Using the grid + +Utilize the Bootstrap grid system within a modal by nesting `.container-fluid` within the `.modal-body`. Then, use the normal grid system classes as you would anywhere else. + +<div class="modal fade" id="gridSystemModal" tabindex="-1" aria-labelledby="gridModalLabel" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="gridModalLabel">Grids in modals</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <div class="container-fluid bd-example-row"> + <div class="row"> + <div class="col-md-4">.col-md-4</div> + <div class="col-md-4 ms-auto">.col-md-4 .ms-auto</div> + </div> + <div class="row"> + <div class="col-md-3 ms-auto">.col-md-3 .ms-auto</div> + <div class="col-md-2 ms-auto">.col-md-2 .ms-auto</div> + </div> + <div class="row"> + <div class="col-md-6 ms-auto">.col-md-6 .ms-auto</div> + </div> + <div class="row"> + <div class="col-sm-9"> + Level 1: .col-sm-9 + <div class="row"> + <div class="col-8 col-sm-6"> + Level 2: .col-8 .col-sm-6 + </div> + <div class="col-4 col-sm-6"> + Level 2: .col-4 .col-sm-6 + </div> + </div> + </div> + </div> + </div> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Save changes</button> + </div> + </div> + </div> +</div> + +<div class="bd-example"> +<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#gridSystemModal"> + Launch demo modal +</button> +</div> + +```html +<div class="modal-body"> + <div class="container-fluid"> + <div class="row"> + <div class="col-md-4">.col-md-4</div> + <div class="col-md-4 ms-auto">.col-md-4 .ms-auto</div> + </div> + <div class="row"> + <div class="col-md-3 ms-auto">.col-md-3 .ms-auto</div> + <div class="col-md-2 ms-auto">.col-md-2 .ms-auto</div> + </div> + <div class="row"> + <div class="col-md-6 ms-auto">.col-md-6 .ms-auto</div> + </div> + <div class="row"> + <div class="col-sm-9"> + Level 1: .col-sm-9 + <div class="row"> + <div class="col-8 col-sm-6"> + Level 2: .col-8 .col-sm-6 + </div> + <div class="col-4 col-sm-6"> + Level 2: .col-4 .col-sm-6 + </div> + </div> + </div> + </div> + </div> +</div> +``` + +### Varying modal content + +Have a bunch of buttons that all trigger the same modal with slightly different contents? Use `event.relatedTarget` and [HTML `data-bs-*` attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) to vary the contents of the modal depending on which button was clicked. + +Below is a live demo followed by example HTML and JavaScript. For more information, [read the modal events docs](#events) for details on `relatedTarget`. + +{{< example stackblitz_add_js="true" >}} +<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@mdo">Open modal for @mdo</button> +<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@fat">Open modal for @fat</button> +<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@getbootstrap">Open modal for @getbootstrap</button> + +<div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalLabel">New message</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + <form> + <div class="mb-3"> + <label for="recipient-name" class="col-form-label">Recipient:</label> + <input type="text" class="form-control" id="recipient-name"> + </div> + <div class="mb-3"> + <label for="message-text" class="col-form-label">Message:</label> + <textarea class="form-control" id="message-text"></textarea> + </div> + </form> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + <button type="button" class="btn btn-primary">Send message</button> + </div> + </div> + </div> +</div> +{{< /example >}} + +```js +const exampleModal = document.getElementById('exampleModal') +exampleModal.addEventListener('show.bs.modal', event => { + // Button that triggered the modal + const button = event.relatedTarget + // Extract info from data-bs-* attributes + const recipient = button.getAttribute('data-bs-whatever') + // If necessary, you could initiate an AJAX request here + // and then do the updating in a callback. + // + // Update the modal's content. + const modalTitle = exampleModal.querySelector('.modal-title') + const modalBodyInput = exampleModal.querySelector('.modal-body input') + + modalTitle.textContent = `New message to ${recipient}` + modalBodyInput.value = recipient +}) +``` + +### Toggle between modals + +Toggle between multiple modals with some clever placement of the `data-bs-target` and `data-bs-toggle` attributes. For example, you could toggle a password reset modal from within an already open sign in modal. **Please note multiple modals cannot be open at the same time**—this method simply toggles between two separate modals. + +{{< example >}} +<div class="modal fade" id="exampleModalToggle" aria-hidden="true" aria-labelledby="exampleModalToggleLabel" tabindex="-1"> + <div class="modal-dialog modal-dialog-centered"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalToggleLabel">Modal 1</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + Show a second modal and hide this one with the button below. + </div> + <div class="modal-footer"> + <button class="btn btn-primary" data-bs-target="#exampleModalToggle2" data-bs-toggle="modal">Open second modal</button> + </div> + </div> + </div> +</div> +<div class="modal fade" id="exampleModalToggle2" aria-hidden="true" aria-labelledby="exampleModalToggleLabel2" tabindex="-1"> + <div class="modal-dialog modal-dialog-centered"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-5" id="exampleModalToggleLabel2">Modal 2</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + Hide this modal and show the first with the button below. + </div> + <div class="modal-footer"> + <button class="btn btn-primary" data-bs-target="#exampleModalToggle" data-bs-toggle="modal">Back to first</button> + </div> + </div> + </div> +</div> +<a class="btn btn-primary" data-bs-toggle="modal" href="#exampleModalToggle" role="button">Open first modal</a> +{{< /example >}} + +### Change animation + +The `$modal-fade-transform` variable determines the transform state of `.modal-dialog` before the modal fade-in animation, the `$modal-show-transform` variable determines the transform of `.modal-dialog` at the end of the modal fade-in animation. + +If you want for example a zoom-in animation, you can set `$modal-fade-transform: scale(.8)`. + +### Remove animation + +For modals that simply appear rather than fade in to view, remove the `.fade` class from your modal markup. + +```html +<div class="modal" tabindex="-1" aria-labelledby="..." aria-hidden="true"> + ... +</div> +``` + +### Dynamic heights + +If the height of a modal changes while it is open, you should call `myModal.handleUpdate()` to readjust the modal's position in case a scrollbar appears. + +### Accessibility + +Be sure to add `aria-labelledby="..."`, referencing the modal title, to `.modal`. Additionally, you may give a description of your modal dialog with `aria-describedby` on `.modal`. Note that you don't need to add `role="dialog"` since we already add it via JavaScript. + +### Embedding YouTube videos + +Embedding YouTube videos in modals requires additional JavaScript not in Bootstrap to automatically stop playback and more. [See this helpful Stack Overflow post](https://stackoverflow.com/questions/18622508/bootstrap-3-and-youtube-in-modal) for more information. + +## Optional sizes + +Modals have three optional sizes, available via modifier classes to be placed on a `.modal-dialog`. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports. + +{{< bs-table "table" >}} +| Size | Class | Modal max-width +| --- | --- | --- | +| Small | `.modal-sm` | `300px` | +| Default | <span class="text-muted">None</span> | `500px` | +| Large | `.modal-lg` | `800px` | +| Extra large | `.modal-xl` | `1140px` | +{{< /bs-table >}} + +Our default modal without modifier class constitutes the "medium" size modal. + +<div class="bd-example"> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalXl">Extra large modal</button> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalLg">Large modal</button> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalSm">Small modal</button> +</div> + +```html +<div class="modal-dialog modal-xl">...</div> +<div class="modal-dialog modal-lg">...</div> +<div class="modal-dialog modal-sm">...</div> +``` + +<div class="modal fade" id="exampleModalXl" tabindex="-1" aria-labelledby="exampleModalXlLabel" aria-hidden="true"> + <div class="modal-dialog modal-xl"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalXlLabel">Extra large modal</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + </div> + </div> +</div> + +<div class="modal fade" id="exampleModalLg" tabindex="-1" aria-labelledby="exampleModalLgLabel" aria-hidden="true"> + <div class="modal-dialog modal-lg"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalLgLabel">Large modal</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + </div> + </div> +</div> + +<div class="modal fade" id="exampleModalSm" tabindex="-1" aria-labelledby="exampleModalSmLabel" aria-hidden="true"> + <div class="modal-dialog modal-sm"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalSmLabel">Small modal</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + </div> + </div> +</div> + +## Fullscreen Modal + +Another override is the option to pop up a modal that covers the user viewport, available via modifier classes that are placed on a `.modal-dialog`. + +{{< bs-table >}} +| Class | Availability | +| --- | --- | --- | +| `.modal-fullscreen` | Always | +| `.modal-fullscreen-sm-down` | `576px` | +| `.modal-fullscreen-md-down` | `768px` | +| `.modal-fullscreen-lg-down` | `992px` | +| `.modal-fullscreen-xl-down` | `1200px` | +| `.modal-fullscreen-xxl-down` | `1400px` | +{{< /bs-table >}} + +<div class="bd-example"> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalFullscreen">Full screen</button> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalFullscreenSm">Full screen below sm</button> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalFullscreenMd">Full screen below md</button> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalFullscreenLg">Full screen below lg</button> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalFullscreenXl">Full screen below xl</button> + <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalFullscreenXxl">Full screen below xxl</button> +</div> + +```html +<!-- Full screen modal --> +<div class="modal-dialog modal-fullscreen-sm-down"> + ... +</div> +``` + +<div class="modal fade" id="exampleModalFullscreen" tabindex="-1" aria-labelledby="exampleModalFullscreenLabel" aria-hidden="true"> + <div class="modal-dialog modal-fullscreen"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalFullscreenLabel">Full screen modal</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + </div> + </div> + </div> +</div> + +<div class="modal fade" id="exampleModalFullscreenSm" tabindex="-1" aria-labelledby="exampleModalFullscreenSmLabel" aria-hidden="true"> + <div class="modal-dialog modal-fullscreen-sm-down"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalFullscreenSmLabel">Full screen below sm</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + </div> + </div> + </div> +</div> + +<div class="modal fade" id="exampleModalFullscreenMd" tabindex="-1" aria-labelledby="exampleModalFullscreenMdLabel" aria-hidden="true"> + <div class="modal-dialog modal-fullscreen-md-down"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalFullscreenMdLabel">Full screen below md</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + </div> + </div> + </div> +</div> + +<div class="modal fade" id="exampleModalFullscreenLg" tabindex="-1" aria-labelledby="exampleModalFullscreenLgLabel" aria-hidden="true"> + <div class="modal-dialog modal-fullscreen-lg-down"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalFullscreenLgLabel">Full screen below lg</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + </div> + </div> + </div> +</div> + +<div class="modal fade" id="exampleModalFullscreenXl" tabindex="-1" aria-labelledby="exampleModalFullscreenXlLabel" aria-hidden="true"> + <div class="modal-dialog modal-fullscreen-xl-down"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalFullscreenXlLabel">Full screen below xl</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + </div> + </div> + </div> +</div> + +<div class="modal fade" id="exampleModalFullscreenXxl" tabindex="-1" aria-labelledby="exampleModalFullscreenXxlLabel" aria-hidden="true"> + <div class="modal-dialog modal-fullscreen-xxl-down"> + <div class="modal-content"> + <div class="modal-header"> + <h1 class="modal-title fs-4" id="exampleModalFullscreenXxlLabel">Full screen below xxl</h1> + <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> + </div> + <div class="modal-body"> + ... + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> + </div> + </div> + </div> +</div> + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, modals now use local CSS variables on `.modal` and `.modal-backdrop` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="modal-css-vars" file="scss/_modal.scss" >}} + +{{< scss-docs name="modal-backdrop-css-vars" file="scss/_modal.scss" >}} + +### Sass variables + +{{< scss-docs name="modal-variables" file="scss/_variables.scss" >}} + +### Loop + +[Responsive fullscreen modals](#fullscreen-modal) are generated via the `$breakpoints` map and a loop in `scss/_modal.scss`. + +{{< scss-docs name="modal-fullscreen-loop" file="scss/_modal.scss" >}} + +## Usage + +The modal plugin toggles your hidden content on demand, via data attributes or JavaScript. It also overrides default scrolling behavior and generates a `.modal-backdrop` to provide a click area for dismissing shown modals when clicking outside the modal. + +### Via data attributes + +#### Toggle + +Activate a modal without writing JavaScript. Set `data-bs-toggle="modal"` on a controller element, like a button, along with a `data-bs-target="#foo"` or `href="#foo"` to target a specific modal to toggle. + +```html +<button type="button" data-bs-toggle="modal" data-bs-target="#myModal">Launch modal</button> +``` + +#### Dismiss + +{{% js-dismiss "modal" %}} + +{{< callout warning >}} +While both ways to dismiss a modal are supported, keep in mind that dismissing from outside a modal does not match the [ARIA Authoring Practices Guide dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/). Do this at your own risk. +{{< /callout >}} + +### Via JavaScript + +Create a modal with a single line of JavaScript: + +```js +const myModal = new bootstrap.Modal(document.getElementById('myModal'), options) +// or +const myModalAlternative = new bootstrap.Modal('#myModal', options) +``` + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< bs-table "table" >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `backdrop` | boolean, `'static'` | `true` | Includes a modal-backdrop element. Alternatively, specify `static` for a backdrop which doesn't close the modal when clicked. | +| `focus` | boolean | `true` | Puts the focus on the modal when initialized. | +| `keyboard` | boolean | `true` | Closes the modal when escape key is pressed. | +{{< /bs-table >}} + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +#### Passing options + +Activates your content as a modal. Accepts an optional options `object`. + +```js +const myModal = new bootstrap.Modal('#myModal', { + keyboard: false +}) +``` + +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `dispose` | Destroys an element's modal. (Removes stored data on the DOM element) | +| `getInstance` | *Static* method which allows you to get the modal instance associated with a DOM element. | +| `getOrCreateInstance` | *Static* method which allows you to get the modal instance associated with a DOM element, or create a new one in case it wasn't initialized. | +| `handleUpdate` | Manually readjust the modal's position if the height of a modal changes while it is open (i.e. in case a scrollbar appears). | +| `hide` | Manually hides a modal. **Returns to the caller before the modal has actually been hidden** (i.e. before the `hidden.bs.modal` event occurs). | +| `show` | Manually opens a modal. **Returns to the caller before the modal has actually been shown** (i.e. before the `shown.bs.modal` event occurs). Also, you can pass a DOM element as an argument that can be received in the modal events (as the `relatedTarget` property). (i.e. `const modalToggle = document.getElementById('toggleMyModal'); myModal.show(modalToggle)`. | +| `toggle` | Manually toggles a modal. **Returns to the caller before the modal has actually been shown or hidden** (i.e. before the `shown.bs.modal` or `hidden.bs.modal` event occurs). | +{{< /bs-table >}} + +### Events + +Bootstrap's modal class exposes a few events for hooking into modal functionality. All modal events are fired at the modal itself (i.e. at the `<div class="modal">`). + +{{< bs-table >}} +| Event | Description | +| --- | --- | +| `hide.bs.modal` | This event is fired immediately when the `hide` instance method has been called. | +| `hidden.bs.modal` | This event is fired when the modal has finished being hidden from the user (will wait for CSS transitions to complete). | +| `hidePrevented.bs.modal` | This event is fired when the modal is shown, its backdrop is `static` and a click outside of the modal is performed. The event is also fired when the escape key is pressed and the `keyboard` option is set to `false`. | +| `show.bs.modal` | This event fires immediately when the `show` instance method is called. If caused by a click, the clicked element is available as the `relatedTarget` property of the event. | +| `shown.bs.modal` | This event is fired when the modal has been made visible to the user (will wait for CSS transitions to complete). If caused by a click, the clicked element is available as the `relatedTarget` property of the event. | +{{< /bs-table >}} + +```js +const myModalEl = document.getElementById('myModal') +myModalEl.addEventListener('hidden.bs.modal', event => { + // do something... +}) +``` diff --git a/site/content/docs/5.2/components/navbar.md b/site/content/docs/5.2/components/navbar.md new file mode 100644 index 0000000..7cbc4e2 --- /dev/null +++ b/site/content/docs/5.2/components/navbar.md @@ -0,0 +1,813 @@ +--- +layout: docs +title: Navbar +description: Documentation and examples for Bootstrap's powerful, responsive navigation header, the navbar. Includes support for branding, navigation, and more, including support for our collapse plugin. +group: components +toc: true +--- + +## How it works + +Here's what you need to know before getting started with the navbar: + +- Navbars require a wrapping `.navbar` with `.navbar-expand{-sm|-md|-lg|-xl|-xxl}` for responsive collapsing and [color scheme](#color-schemes) classes. +- Navbars and their contents are fluid by default. Change the [container](#containers) to limit their horizontal width in different ways. +- Use our [spacing]({{< docsref "/utilities/spacing" >}}) and [flex]({{< docsref "/utilities/flex" >}}) utility classes for controlling spacing and alignment within navbars. +- Navbars are responsive by default, but you can easily modify them to change that. Responsive behavior depends on our Collapse JavaScript plugin. +- Ensure accessibility by using a `<nav>` element or, if using a more generic element such as a `<div>`, add a `role="navigation"` to every navbar to explicitly identify it as a landmark region for users of assistive technologies. +- Indicate the current item by using `aria-current="page"` for the current page or `aria-current="true"` for the current item in a set. +- **New in v5.2.0:** Navbars can be themed with CSS variables that are scoped to the `.navbar` base class. `.navbar-light` has been deprecated and `.navbar-dark` has been rewritten to override CSS variables instead of adding additional styles. + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +## Supported content + +Navbars come with built-in support for a handful of sub-components. Choose from the following as needed: + +- `.navbar-brand` for your company, product, or project name. +- `.navbar-nav` for a full-height and lightweight navigation (including support for dropdowns). +- `.navbar-toggler` for use with our collapse plugin and other [navigation toggling](#responsive-behaviors) behaviors. +- Flex and spacing utilities for any form controls and actions. +- `.navbar-text` for adding vertically centered strings of text. +- `.collapse.navbar-collapse` for grouping and hiding navbar contents by a parent breakpoint. +- Add an optional `.navbar-scroll` to set a `max-height` and [scroll expanded navbar content](#scrolling). + +Here's an example of all the sub-components included in a responsive light-themed navbar that automatically collapses at the `lg` (large) breakpoint. + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarSupportedContent"> + <ul class="navbar-nav me-auto mb-2 mb-lg-0"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </a> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> + </ul> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-success" type="submit">Search</button> + </form> + </div> + </div> +</nav> +{{< /example >}} + +This example uses [background]({{< docsref "/utilities/background" >}}) (`bg-light`) and [spacing]({{< docsref "/utilities/spacing" >}}) (`me-auto`, `mb-2`, `mb-lg-0`, `me-2`) utility classes. + +### Brand + +The `.navbar-brand` can be applied to most elements, but an anchor works best, as some elements might require utility classes or custom styles. + +#### Text + +Add your text within an element with the `.navbar-brand` class. + +{{< example >}} +<!-- As a link --> +<nav class="navbar bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + </div> +</nav> + +<!-- As a heading --> +<nav class="navbar bg-light"> + <div class="container-fluid"> + <span class="navbar-brand mb-0 h1">Navbar</span> + </div> +</nav> +{{< /example >}} + +#### Image + +You can replace the text within the `.navbar-brand` with an `<img>`. + +{{< example >}} +<nav class="navbar bg-light"> + <div class="container"> + <a class="navbar-brand" href="#"> + <img src="/docs/{{< param docs_version >}}/assets/brand/bootstrap-logo.svg" alt="Bootstrap" width="30" height="24"> + </a> + </div> +</nav> +{{< /example >}} + +#### Image and text + +You can also make use of some additional utilities to add an image and text at the same time. Note the addition of `.d-inline-block` and `.align-text-top` on the `<img>`. + +{{< example >}} +<nav class="navbar bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#"> + <img src="/docs/{{< param docs_version >}}/assets/brand/bootstrap-logo.svg" alt="Logo" width="30" height="24" class="d-inline-block align-text-top"> + Bootstrap + </a> + </div> +</nav> +{{< /example >}} + +### Nav + +Navbar navigation links build on our `.nav` options with their own modifier class and require the use of [toggler classes](#toggler) for proper responsive styling. **Navigation in navbars will also grow to occupy as much horizontal space as possible** to keep your navbar contents securely aligned. + +Add the `.active` class on `.nav-link` to indicate the current page. + +Please note that you should also add the `aria-current` attribute on the active `.nav-link`. + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarNav"> + <ul class="navbar-nav"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Features</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Pricing</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> + </ul> + </div> + </div> +</nav> +{{< /example >}} + +And because we use classes for our navs, you can avoid the list-based approach entirely if you like. + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNavAltMarkup" aria-controls="navbarNavAltMarkup" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarNavAltMarkup"> + <div class="navbar-nav"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + <a class="nav-link" href="#">Features</a> + <a class="nav-link" href="#">Pricing</a> + <a class="nav-link disabled">Disabled</a> + </div> + </div> + </div> +</nav> +{{< /example >}} + +You can also use dropdowns in your navbar. Dropdown menus require a wrapping element for positioning, so be sure to use separate and nested elements for `.nav-item` and `.nav-link` as shown below. + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNavDropdown" aria-controls="navbarNavDropdown" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarNavDropdown"> + <ul class="navbar-nav"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Features</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Pricing</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown link + </a> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> + </li> + </ul> + </div> + </div> +</nav> +{{< /example >}} + +### Forms + +Place various form controls and components within a navbar: + +{{< example >}} +<nav class="navbar bg-light"> + <div class="container-fluid"> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-success" type="submit">Search</button> + </form> + </div> +</nav> +{{< /example >}} + +Immediate child elements of `.navbar` use flex layout and will default to `justify-content: space-between`. Use additional [flex utilities]({{< docsref "/utilities/flex" >}}) as needed to adjust this behavior. + +{{< example >}} +<nav class="navbar bg-light"> + <div class="container-fluid"> + <a class="navbar-brand">Navbar</a> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-success" type="submit">Search</button> + </form> + </div> +</nav> +{{< /example >}} + +Input groups work, too. If your navbar is an entire form, or mostly a form, you can use the `<form>` element as the container and save some HTML. + +{{< example >}} +<nav class="navbar bg-light"> + <form class="container-fluid"> + <div class="input-group"> + <span class="input-group-text" id="basic-addon1">@</span> + <input type="text" class="form-control" placeholder="Username" aria-label="Username" aria-describedby="basic-addon1"> + </div> + </form> +</nav> +{{< /example >}} + +Various buttons are supported as part of these navbar forms, too. This is also a great reminder that vertical alignment utilities can be used to align different sized elements. + +{{< example >}} +<nav class="navbar bg-light"> + <form class="container-fluid justify-content-start"> + <button class="btn btn-outline-success me-2" type="button">Main button</button> + <button class="btn btn-sm btn-outline-secondary" type="button">Smaller button</button> + </form> +</nav> +{{< /example >}} + +### Text + +Navbars may contain bits of text with the help of `.navbar-text`. This class adjusts vertical alignment and horizontal spacing for strings of text. + +{{< example >}} +<nav class="navbar bg-light"> + <div class="container-fluid"> + <span class="navbar-text"> + Navbar text with an inline element + </span> + </div> +</nav> +{{< /example >}} + +Mix and match with other components and utilities as needed. + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar w/ text</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarText" aria-controls="navbarText" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarText"> + <ul class="navbar-nav me-auto mb-2 mb-lg-0"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Features</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Pricing</a> + </li> + </ul> + <span class="navbar-text"> + Navbar text with an inline element + </span> + </div> + </div> +</nav> +{{< /example >}} + +## Color schemes + +{{< callout warning >}} +**New in v5.2.0:** Navbar theming is now powered by CSS variables and `.navbar-light` has been deprecated. CSS variables are applied to `.navbar`, defaulting to the "light" appearance, and can be overridden with `.navbar-dark`. +{{< /callout >}} + +Navbar themes are easier than ever thanks to Bootstrap's combination of Sass and CSS variables. The default is our "light navbar" for use with light background colors, but you can also apply `.navbar-dark` for dark background colors. Then, customize with `.bg-*` utilities. + +<div class="bd-example"> + <nav class="navbar navbar-expand-lg navbar-dark bg-dark"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarColor01" aria-controls="navbarColor01" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarColor01"> + <ul class="navbar-nav me-auto mb-2 mb-lg-0"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Features</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Pricing</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">About</a> + </li> + </ul> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-light" type="submit">Search</button> + </form> + </div> + </div> + </nav> + + <nav class="navbar navbar-expand-lg navbar-dark bg-primary"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarColor02" aria-controls="navbarColor02" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarColor02"> + <ul class="navbar-nav me-auto mb-2 mb-lg-0"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Features</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Pricing</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">About</a> + </li> + </ul> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-light" type="submit">Search</button> + </form> + </div> + </div> + </nav> + + <nav class="navbar navbar-expand-lg" style="background-color: #e3f2fd;"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarColor03" aria-controls="navbarColor03" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarColor03"> + <ul class="navbar-nav me-auto mb-2 mb-lg-0"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Features</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Pricing</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">About</a> + </li> + </ul> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-primary" type="submit">Search</button> + </form> + </div> + </div> + </nav> +</div> + +```html +<nav class="navbar navbar-dark bg-dark"> + <!-- Navbar content --> +</nav> + +<nav class="navbar navbar-dark bg-primary"> + <!-- Navbar content --> +</nav> + +<nav class="navbar" style="background-color: #e3f2fd;"> + <!-- Navbar content --> +</nav> +``` + +## Containers + +Although it's not required, you can wrap a navbar in a `.container` to center it on a page–though note that an inner container is still required. Or you can add a container inside the `.navbar` to only center the contents of a [fixed or static top navbar](#placement). + +{{< example >}} +<div class="container"> + <nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + </div> + </nav> +</div> +{{< /example >}} + +Use any of the responsive containers to change how wide the content in your navbar is presented. + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-md"> + <a class="navbar-brand" href="#">Navbar</a> + </div> +</nav> +{{< /example >}} + +## Placement + +Use our [position utilities]({{< docsref "/utilities/position" >}}) to place navbars in non-static positions. Choose from fixed to the top, fixed to the bottom, stickied to the top (scrolls with the page until it reaches the top, then stays there), or stickied to the bottom (scrolls with the page until it reaches the bottom, then stays there). + +Fixed navbars use `position: fixed`, meaning they're pulled from the normal flow of the DOM and may require custom CSS (e.g., `padding-top` on the `<body>`) to prevent overlap with other elements. + +{{< example >}} +<nav class="navbar bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Default</a> + </div> +</nav> +{{< /example >}} + +{{< example >}} +<nav class="navbar fixed-top bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Fixed top</a> + </div> +</nav> +{{< /example >}} + +{{< example >}} +<nav class="navbar fixed-bottom bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Fixed bottom</a> + </div> +</nav> +{{< /example >}} + +{{< example >}} +<nav class="navbar sticky-top bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Sticky top</a> + </div> +</nav> +{{< /example >}} + +{{< example >}} +<nav class="navbar sticky-bottom bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Sticky bottom</a> + </div> +</nav> +{{< /example >}} + +## Scrolling + +Add `.navbar-nav-scroll` to a `.navbar-nav` (or other navbar sub-component) to enable vertical scrolling within the toggleable contents of a collapsed navbar. By default, scrolling kicks in at `75vh` (or 75% of the viewport height), but you can override that with the local CSS custom property `--bs-navbar-height` or custom styles. At larger viewports when the navbar is expanded, content will appear as it does in a default navbar. + +Please note that this behavior comes with a potential drawback of `overflow`—when setting `overflow-y: auto` (required to scroll the content here), `overflow-x` is the equivalent of `auto`, which will crop some horizontal content. + +Here's an example navbar using `.navbar-nav-scroll` with `style="--bs-scroll-height: 100px;"`, with some extra margin utilities for optimum spacing. + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar scroll</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarScroll" aria-controls="navbarScroll" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarScroll"> + <ul class="navbar-nav me-auto my-2 my-lg-0 navbar-nav-scroll" style="--bs-scroll-height: 100px;"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false"> + Link + </a> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Link</a> + </li> + </ul> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-success" type="submit">Search</button> + </form> + </div> + </div> +</nav> +{{< /example >}} + +## Responsive behaviors + +Navbars can use `.navbar-toggler`, `.navbar-collapse`, and `.navbar-expand{-sm|-md|-lg|-xl|-xxl}` classes to determine when their content collapses behind a button. In combination with other utilities, you can easily choose when to show or hide particular elements. + +For navbars that never collapse, add the `.navbar-expand` class on the navbar. For navbars that always collapse, don't add any `.navbar-expand` class. + +### Toggler + +Navbar togglers are left-aligned by default, but should they follow a sibling element like a `.navbar-brand`, they'll automatically be aligned to the far right. Reversing your markup will reverse the placement of the toggler. Below are examples of different toggle styles. + +With no `.navbar-brand` shown at the smallest breakpoint: + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarTogglerDemo01" aria-controls="navbarTogglerDemo01" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarTogglerDemo01"> + <a class="navbar-brand" href="#">Hidden brand</a> + <ul class="navbar-nav me-auto mb-2 mb-lg-0"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> + </ul> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-success" type="submit">Search</button> + </form> + </div> + </div> +</nav> +{{< /example >}} + +With a brand name shown on the left and toggler on the right: + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarTogglerDemo02" aria-controls="navbarTogglerDemo02" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="collapse navbar-collapse" id="navbarTogglerDemo02"> + <ul class="navbar-nav me-auto mb-2 mb-lg-0"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> + </ul> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-success" type="submit">Search</button> + </form> + </div> + </div> +</nav> +{{< /example >}} + +With a toggler on the left and brand name on the right: + +{{< example >}} +<nav class="navbar navbar-expand-lg bg-light"> + <div class="container-fluid"> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarTogglerDemo03" aria-controls="navbarTogglerDemo03" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + <a class="navbar-brand" href="#">Navbar</a> + <div class="collapse navbar-collapse" id="navbarTogglerDemo03"> + <ul class="navbar-nav me-auto mb-2 mb-lg-0"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> + </ul> + <form class="d-flex" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-success" type="submit">Search</button> + </form> + </div> + </div> +</nav> +{{< /example >}} + +### External content + +Sometimes you want to use the collapse plugin to trigger a container element for content that structurally sits outside of the `.navbar` . Because our plugin works on the `id` and `data-bs-target` matching, that's easily done! + +{{< example >}} +<div class="collapse" id="navbarToggleExternalContent"> + <div class="bg-dark p-4"> + <h5 class="text-white h4">Collapsed content</h5> + <span class="text-muted">Toggleable via the navbar brand.</span> + </div> +</div> +<nav class="navbar navbar-dark bg-dark"> + <div class="container-fluid"> + <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarToggleExternalContent" aria-controls="navbarToggleExternalContent" aria-expanded="false" aria-label="Toggle navigation"> + <span class="navbar-toggler-icon"></span> + </button> + </div> +</nav> +{{< /example >}} + +When you do this, we recommend including additional JavaScript to move the focus programmatically to the container when it is opened. Otherwise, keyboard users and users of assistive technologies will likely have a hard time finding the newly revealed content - particularly if the container that was opened comes *before* the toggler in the document's structure. We also recommend making sure that the toggler has the `aria-controls` attribute, pointing to the `id` of the content container. In theory, this allows assistive technology users to jump directly from the toggler to the container it controls–but support for this is currently quite patchy. + +### Offcanvas + +Transform your expanding and collapsing navbar into an offcanvas drawer with the [offcanvas component]({{< docsref "/components/offcanvas" >}}). We extend both the offcanvas default styles and use our `.navbar-expand-*` classes to create a dynamic and flexible navigation sidebar. + +In the example below, to create an offcanvas navbar that is always collapsed across all breakpoints, omit the `.navbar-expand-*` class entirely. + +{{< example >}} +<nav class="navbar bg-light fixed-top"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Offcanvas navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasNavbar" aria-controls="offcanvasNavbar"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasNavbar" aria-labelledby="offcanvasNavbarLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasNavbarLabel">Offcanvas</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + <ul class="navbar-nav justify-content-end flex-grow-1 pe-3"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </a> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li> + <hr class="dropdown-divider"> + </li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> + </li> + </ul> + <form class="d-flex mt-3" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-outline-success" type="submit">Search</button> + </form> + </div> + </div> + </div> +</nav> +{{< /example >}} + +To create an offcanvas navbar that expands into a normal navbar at a specific breakpoint like `lg`, use `.navbar-expand-lg`. + +```html +<nav class="navbar navbar-expand-lg bg-light fixed-top"> + <a class="navbar-brand" href="#">Offcanvas navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="offcanvas" data-bs-target="#navbarOffcanvasLg" aria-controls="navbarOffcanvasLg"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="offcanvas offcanvas-end" tabindex="-1" id="navbarOffcanvasLg" aria-labelledby="navbarOffcanvasLgLabel"> + ... + </div> +</nav> +``` + +When using offcanvas in a dark navbar, be aware that you may need to have a dark background on the offcanvas content to avoid the text becoming illegible. In the example below, we add `.navbar-dark` and `.bg-dark` to the `.navbar`, `.text-bg-dark` to the `.offcanvas`, `.dropdown-menu-dark` to `.dropdown-menu`, and `.btn-close-white` to `.btn-close` for proper styling with a dark offcanvas. + +{{< example >}} +<nav class="navbar navbar-dark bg-dark fixed-top"> + <div class="container-fluid"> + <a class="navbar-brand" href="#">Offcanvas dark navbar</a> + <button class="navbar-toggler" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasDarkNavbar" aria-controls="offcanvasDarkNavbar"> + <span class="navbar-toggler-icon"></span> + </button> + <div class="offcanvas offcanvas-end text-bg-dark" tabindex="-1" id="offcanvasDarkNavbar" aria-labelledby="offcanvasDarkNavbarLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasDarkNavbarLabel">Dark offcanvas</h5> + <button type="button" class="btn-close btn-close-white" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + <ul class="navbar-nav justify-content-end flex-grow-1 pe-3"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Home</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false"> + Dropdown + </a> + <ul class="dropdown-menu dropdown-menu-dark"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li> + <hr class="dropdown-divider"> + </li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> + </li> + </ul> + <form class="d-flex mt-3" role="search"> + <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search"> + <button class="btn btn-success" type="submit">Search</button> + </form> + </div> + </div> + </div> +</nav> +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, navbars now use local CSS variables on `.navbar` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="navbar-css-vars" file="scss/_navbar.scss" >}} + +Some additional CSS variables are also present on `.navbar-nav`: + +{{< scss-docs name="navbar-nav-css-vars" file="scss/_navbar.scss" >}} + +Customization through CSS variables can be seen on the `.navbar-dark` class where we override specific values without adding duplicate CSS selectors. + +{{< scss-docs name="navbar-dark-css-vars" file="scss/_navbar.scss" >}} + +### Sass variables + +Variables for all navbars: + +{{< scss-docs name="navbar-variables" file="scss/_variables.scss" >}} + +Variables for the [dark navbar](#color-schemes): + +{{< scss-docs name="navbar-dark-variables" file="scss/_variables.scss" >}} + +### Sass loop + +[Responsive navbar expand/collapse classes](#responsive-behaviors) (e.g., `.navbar-expand-lg`) are combined with the `$breakpoints` map and generated through a loop in `scss/_navbar.scss`. + +{{< scss-docs name="navbar-expand-loop" file="scss/_navbar.scss" >}} diff --git a/site/content/docs/5.2/components/navs-tabs.md b/site/content/docs/5.2/components/navs-tabs.md new file mode 100644 index 0000000..1748dd1 --- /dev/null +++ b/site/content/docs/5.2/components/navs-tabs.md @@ -0,0 +1,671 @@ +--- +layout: docs +title: Navs and tabs +description: Documentation and examples for how to use Bootstrap's included navigation components. +group: components +aliases: "/docs/5.2/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. + +{{< callout info >}} +The base `.nav` component does not include any `.active` state. The following examples include the class, mainly to demonstrate that this particular class does not trigger any special 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. +{{< /callout >}} + +{{< example >}} +<ul class="nav"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +Classes are used throughout, so your markup can be super flexible. Use `<ul>`s like above, `<ol>` if the order of your items is important, or roll your own with a `<nav>` element. Because the `.nav` uses `display: flex`, the nav links behave the same as nav items would, but without the extra markup. + +{{< example >}} +<nav class="nav"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + <a class="nav-link" href="#">Link</a> + <a class="nav-link" href="#">Link</a> + <a class="nav-link disabled">Disabled</a> +</nav> +{{< /example >}} + +## Available styles + +Change the style of `.nav`s component with modifiers and utilities. Mix and match as needed, or build your own. + +### Horizontal alignment + +Change the horizontal alignment of your nav with [flexbox utilities]({{< docsref "/layout/grid#horizontal-alignment" >}}). By default, navs are left-aligned, but you can easily change them to center or right aligned. + +Centered with `.justify-content-center`: + +{{< example >}} +<ul class="nav justify-content-center"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +Right-aligned with `.justify-content-end`: + +{{< example >}} +<ul class="nav justify-content-end"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +### 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`). + +{{< example >}} +<ul class="nav flex-column"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +As always, vertical navigation is possible without `<ul>`s, too. + +{{< example >}} +<nav class="nav flex-column"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + <a class="nav-link" href="#">Link</a> + <a class="nav-link" href="#">Link</a> + <a class="nav-link disabled">Disabled</a> +</nav> +{{< /example >}} + +### Tabs + +Takes the basic nav from above and adds the `.nav-tabs` class to generate a tabbed interface. Use them to create tabbable regions with our [tab JavaScript plugin](#javascript-behavior). + +{{< example >}} +<ul class="nav nav-tabs"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +### Pills + +Take that same HTML, but use `.nav-pills` instead: + +{{< example >}} +<ul class="nav nav-pills"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +### Fill and justify + +Force your `.nav`'s contents to extend the full available width 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. + +{{< example >}} +<ul class="nav nav-pills nav-fill"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Much longer nav link</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +When using a `<nav>`-based navigation, you can safely omit `.nav-item` as only `.nav-link` is required for styling `<a>` elements. + +{{< example >}} +<nav class="nav nav-pills nav-fill"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + <a class="nav-link" href="#">Much longer nav link</a> + <a class="nav-link" href="#">Link</a> + <a class="nav-link disabled">Disabled</a> +</nav> +{{< /example >}} + +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. + +{{< example >}} +<ul class="nav nav-pills nav-justified"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Much longer nav link</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +Similar to the `.nav-fill` example using a `<nav>`-based navigation. + +{{< example >}} +<nav class="nav nav-pills nav-justified"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + <a class="nav-link" href="#">Much longer nav link</a> + <a class="nav-link" href="#">Link</a> + <a class="nav-link disabled">Disabled</a> +</nav> + +{{< /example >}} +## 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. + +{{< example >}} +<nav class="nav nav-pills flex-column flex-sm-row"> + <a class="flex-sm-fill text-sm-center nav-link active" aria-current="page" href="#">Active</a> + <a class="flex-sm-fill text-sm-center nav-link" href="#">Longer nav link</a> + <a class="flex-sm-fill text-sm-center nav-link" href="#">Link</a> + <a class="flex-sm-fill text-sm-center nav-link disabled">Disabled</a> +</nav> +{{< /example >}} + +## 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 `<ul>`, or wrap a `<nav>` element around the whole navigation. Do not add the role to the `<ul>` itself, as this would prevent it from being announced as an actual list by assistive technologies. + +Note that navigation bars, even if visually styled as tabs with the `.nav-tabs` class, should **not** be given `role="tablist"`, `role="tab"` or `role="tabpanel"` attributes. These are only appropriate for dynamic tabbed interfaces, as described in the [ARIA Authoring Practices Guide tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/). See [JavaScript behavior](#javascript-behavior) for dynamic tabbed interfaces in this section for an example. The `aria-current` attribute is not necessary on dynamic tabbed interfaces since our JavaScript handles the selected state by adding `aria-selected="true"` on the active tab. + +## Using dropdowns + +Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin]({{< docsref "/components/dropdowns#usage" >}}). + +### Tabs with dropdowns + +{{< example >}} +<ul class="nav nav-tabs"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Dropdown</a> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +### Pills with dropdowns + +{{< example >}} +<ul class="nav nav-pills"> + <li class="nav-item"> + <a class="nav-link active" aria-current="page" href="#">Active</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Dropdown</a> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + </li> + <li class="nav-item"> + <a class="nav-link" href="#">Link</a> + </li> + <li class="nav-item"> + <a class="nav-link disabled">Disabled</a> + </li> +</ul> +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, navs now use local CSS variables on `.nav`, `.nav-tabs`, and `.nav-pills` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +On the `.nav` base class: + +{{< scss-docs name="nav-css-vars" file="scss/_nav.scss" >}} + +On the `.nav-tabs` modifier class: + +{{< scss-docs name="nav-tabs-css-vars" file="scss/_nav.scss" >}} + +On the `.nav-pills` modifier class: + +{{< scss-docs name="nav-pills-css-vars" file="scss/_nav.scss" >}} + +### Sass variables + +{{< scss-docs name="nav-variables" file="scss/_variables.scss" >}} + +## 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. + +<div class="bd-example"> + <ul class="nav nav-tabs mb-3" id="myTab" role="tablist"> + <li class="nav-item" role="presentation"> + <button class="nav-link active" id="home-tab" data-bs-toggle="tab" data-bs-target="#home-tab-pane" type="button" role="tab" aria-controls="home-tab-pane" aria-selected="true">Home</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="profile-tab" data-bs-toggle="tab" data-bs-target="#profile-tab-pane" type="button" role="tab" aria-controls="profile-tab-pane" aria-selected="false">Profile</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="contact-tab" data-bs-toggle="tab" data-bs-target="#contact-tab-pane" type="button" role="tab" aria-controls="contact-tab-pane" aria-selected="false">Contact</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="disabled-tab" data-bs-toggle="tab" data-bs-target="#disabled-tab-pane" type="button" role="tab" aria-controls="disabled-tab-pane" aria-selected="false" disabled>Disabled</button> + </li> + </ul> + <div class="tab-content" id="myTabContent"> + <div class="tab-pane fade show active" id="home-tab-pane" role="tabpanel" aria-labelledby="home-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Home tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="profile-tab-pane" role="tabpanel" aria-labelledby="profile-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Profile tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="contact-tab-pane" role="tabpanel" aria-labelledby="contact-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Contact tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="disabled-tab-pane" role="tabpanel" aria-labelledby="disabled-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Disabled tab's</strong> associated content.</p> + </div> + </div> +</div> + +```html +<ul class="nav nav-tabs" id="myTab" role="tablist"> + <li class="nav-item" role="presentation"> + <button class="nav-link active" id="home-tab" data-bs-toggle="tab" data-bs-target="#home-tab-pane" type="button" role="tab" aria-controls="home-tab-pane" aria-selected="true">Home</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="profile-tab" data-bs-toggle="tab" data-bs-target="#profile-tab-pane" type="button" role="tab" aria-controls="profile-tab-pane" aria-selected="false">Profile</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="contact-tab" data-bs-toggle="tab" data-bs-target="#contact-tab-pane" type="button" role="tab" aria-controls="contact-tab-pane" aria-selected="false">Contact</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="disabled-tab" data-bs-toggle="tab" data-bs-target="#disabled-tab-pane" type="button" role="tab" aria-controls="disabled-tab-pane" aria-selected="false" disabled>Disabled</button> + </li> +</ul> +<div class="tab-content" id="myTabContent"> + <div class="tab-pane fade show active" id="home-tab-pane" role="tabpanel" aria-labelledby="home-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="profile-tab-pane" role="tabpanel" aria-labelledby="profile-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="contact-tab-pane" role="tabpanel" aria-labelledby="contact-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="disabled-tab-pane" role="tabpanel" aria-labelledby="disabled-tab" tabindex="0">...</div> +</div> +``` + +To help fit your needs, this works with `<ul>`-based markup, as shown above, or with any arbitrary "roll your own" markup. Note that if you're using `<nav>`, 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 `<div>`) and wrap the `<nav>` around it. + +<div class="bd-example"> + <nav> + <div class="nav nav-tabs mb-3" id="nav-tab" role="tablist"> + <button class="nav-link active" id="nav-home-tab" data-bs-toggle="tab" data-bs-target="#nav-home" type="button" role="tab" aria-controls="nav-home" aria-selected="true">Home</button> + <button class="nav-link" id="nav-profile-tab" data-bs-toggle="tab" data-bs-target="#nav-profile" type="button" role="tab" aria-controls="nav-profile" aria-selected="false">Profile</button> + <button class="nav-link" id="nav-contact-tab" data-bs-toggle="tab" data-bs-target="#nav-contact" type="button" role="tab" aria-controls="nav-contact" aria-selected="false">Contact</button> + <button class="nav-link" id="nav-disabled-tab" data-bs-toggle="tab" data-bs-target="#nav-disabled" type="button" role="tab" aria-controls="nav-disabled" aria-selected="false" disabled>Disabled</button> + </div> + </nav> + <div class="tab-content" id="nav-tabContent"> + <div class="tab-pane fade show active" id="nav-home" role="tabpanel" aria-labelledby="nav-home-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Home tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="nav-profile" role="tabpanel" aria-labelledby="nav-profile-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Profile tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="nav-contact" role="tabpanel" aria-labelledby="nav-contact-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Contact tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="nav-disabled" role="tabpanel" aria-labelledby="nav-disabled-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Disabled tab's</strong> associated content.</p> + </div> + </div> +</div> + +```html +<nav> + <div class="nav nav-tabs" id="nav-tab" role="tablist"> + <button class="nav-link active" id="nav-home-tab" data-bs-toggle="tab" data-bs-target="#nav-home" type="button" role="tab" aria-controls="nav-home" aria-selected="true">Home</button> + <button class="nav-link" id="nav-profile-tab" data-bs-toggle="tab" data-bs-target="#nav-profile" type="button" role="tab" aria-controls="nav-profile" aria-selected="false">Profile</button> + <button class="nav-link" id="nav-contact-tab" data-bs-toggle="tab" data-bs-target="#nav-contact" type="button" role="tab" aria-controls="nav-contact" aria-selected="false">Contact</button> + <button class="nav-link" id="nav-disabled-tab" data-bs-toggle="tab" data-bs-target="#nav-disabled" type="button" role="tab" aria-controls="nav-disabled" aria-selected="false" disabled>Disabled</button> + </div> +</nav> +<div class="tab-content" id="nav-tabContent"> + <div class="tab-pane fade show active" id="nav-home" role="tabpanel" aria-labelledby="nav-home-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="nav-profile" role="tabpanel" aria-labelledby="nav-profile-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="nav-contact" role="tabpanel" aria-labelledby="nav-contact-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="nav-disabled" role="tabpanel" aria-labelledby="nav-disabled-tab" tabindex="0">...</div> +</div> +``` + +The tabs plugin also works with pills. + +<div class="bd-example"> + <ul class="nav nav-pills mb-3" id="pills-tab" role="tablist"> + <li class="nav-item" role="presentation"> + <button class="nav-link active" id="pills-home-tab" data-bs-toggle="pill" data-bs-target="#pills-home" type="button" role="tab" aria-controls="pills-home" aria-selected="true">Home</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="pills-profile-tab" data-bs-toggle="pill" data-bs-target="#pills-profile" type="button" role="tab" aria-controls="pills-profile" aria-selected="false">Profile</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="pills-contact-tab" data-bs-toggle="pill" data-bs-target="#pills-contact" type="button" role="tab" aria-controls="pills-contact" aria-selected="false">Contact</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="pills-disabled-tab" data-bs-toggle="pill" data-bs-target="#pills-disabled" type="button" role="tab" aria-controls="pills-disabled" aria-selected="false" disabled>Disabled</button> + </li> + </ul> + <div class="tab-content" id="pills-tabContent"> + <div class="tab-pane fade show active" id="pills-home" role="tabpanel" aria-labelledby="pills-home-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Home tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="pills-profile" role="tabpanel" aria-labelledby="pills-profile-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Profile tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="pills-contact" role="tabpanel" aria-labelledby="pills-contact-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Contact tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="pills-disabled" role="tabpanel" aria-labelledby="pills-disabled-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Disabled tab's</strong> associated content.</p> + </div> + </div> +</div> + +```html +<ul class="nav nav-pills mb-3" id="pills-tab" role="tablist"> + <li class="nav-item" role="presentation"> + <button class="nav-link active" id="pills-home-tab" data-bs-toggle="pill" data-bs-target="#pills-home" type="button" role="tab" aria-controls="pills-home" aria-selected="true">Home</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="pills-profile-tab" data-bs-toggle="pill" data-bs-target="#pills-profile" type="button" role="tab" aria-controls="pills-profile" aria-selected="false">Profile</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="pills-contact-tab" data-bs-toggle="pill" data-bs-target="#pills-contact" type="button" role="tab" aria-controls="pills-contact" aria-selected="false">Contact</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="pills-disabled-tab" data-bs-toggle="pill" data-bs-target="#pills-disabled" type="button" role="tab" aria-controls="pills-disabled" aria-selected="false" disabled>Disabled</button> + </li> +</ul> +<div class="tab-content" id="pills-tabContent"> + <div class="tab-pane fade show active" id="pills-home" role="tabpanel" aria-labelledby="pills-home-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="pills-profile" role="tabpanel" aria-labelledby="pills-profile-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="pills-contact" role="tabpanel" aria-labelledby="pills-contact-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="pills-disabled" role="tabpanel" aria-labelledby="pills-disabled-tab" tabindex="0">...</div> +</div> +``` + +And with vertical pills. Ideally, for vertical tabs, you should also add `aria-orientation="vertical"` to the tab list container. + +<div class="bd-example"> + <div class="d-flex align-items-start"> + <div class="nav flex-column nav-pills me-3" id="v-pills-tab" role="tablist" aria-orientation="vertical"> + <button class="nav-link active" id="v-pills-home-tab" data-bs-toggle="pill" data-bs-target="#v-pills-home" type="button" role="tab" aria-controls="v-pills-home" aria-selected="true">Home</button> + <button class="nav-link" id="v-pills-profile-tab" data-bs-toggle="pill" data-bs-target="#v-pills-profile" type="button" role="tab" aria-controls="v-pills-profile" aria-selected="false">Profile</button> + <button class="nav-link" id="v-pills-disabled-tab" data-bs-toggle="pill" data-bs-target="#v-pills-disabled" type="button" role="tab" aria-controls="v-pills-disabled" aria-selected="false" disabled>Disabled</button> + <button class="nav-link" id="v-pills-messages-tab" data-bs-toggle="pill" data-bs-target="#v-pills-messages" type="button" role="tab" aria-controls="v-pills-messages" aria-selected="false">Messages</button> + <button class="nav-link" id="v-pills-settings-tab" data-bs-toggle="pill" data-bs-target="#v-pills-settings" type="button" role="tab" aria-controls="v-pills-settings" aria-selected="false">Settings</button> + </div> + <div class="tab-content" id="v-pills-tabContent"> + <div class="tab-pane fade show active" id="v-pills-home" role="tabpanel" aria-labelledby="v-pills-home-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Home tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="v-pills-profile" role="tabpanel" aria-labelledby="v-pills-profile-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Profile tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="v-pills-disabled" role="tabpanel" aria-labelledby="v-pills-disabled-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Disabled tab's</strong> associated content.</p> + </div> + <div class="tab-pane fade" id="v-pills-messages" role="tabpanel" aria-labelledby="v-pills-messages-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Messages tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + <div class="tab-pane fade" id="v-pills-settings" role="tabpanel" aria-labelledby="v-pills-settings-tab" tabindex="0"> + <p>This is some placeholder content the <strong>Settings tab's</strong> 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 <code>.nav</code>-powered navigation.</p> + </div> + </div> + </div> +</div> + +```html +<div class="d-flex align-items-start"> + <div class="nav flex-column nav-pills me-3" id="v-pills-tab" role="tablist" aria-orientation="vertical"> + <button class="nav-link active" id="v-pills-home-tab" data-bs-toggle="pill" data-bs-target="#v-pills-home" type="button" role="tab" aria-controls="v-pills-home" aria-selected="true">Home</button> + <button class="nav-link" id="v-pills-profile-tab" data-bs-toggle="pill" data-bs-target="#v-pills-profile" type="button" role="tab" aria-controls="v-pills-profile" aria-selected="false">Profile</button> + <button class="nav-link" id="v-pills-disabled-tab" data-bs-toggle="pill" data-bs-target="#v-pills-disabled" type="button" role="tab" aria-controls="v-pills-disabled" aria-selected="false" disabled>Disabled</button> + <button class="nav-link" id="v-pills-messages-tab" data-bs-toggle="pill" data-bs-target="#v-pills-messages" type="button" role="tab" aria-controls="v-pills-messages" aria-selected="false">Messages</button> + <button class="nav-link" id="v-pills-settings-tab" data-bs-toggle="pill" data-bs-target="#v-pills-settings" type="button" role="tab" aria-controls="v-pills-settings" aria-selected="false">Settings</button> + </div> + <div class="tab-content" id="v-pills-tabContent"> + <div class="tab-pane fade show active" id="v-pills-home" role="tabpanel" aria-labelledby="v-pills-home-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="v-pills-profile" role="tabpanel" aria-labelledby="v-pills-profile-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="v-pills-disabled" role="tabpanel" aria-labelledby="v-pills-disabled-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="v-pills-messages" role="tabpanel" aria-labelledby="v-pills-messages-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="v-pills-settings" role="tabpanel" aria-labelledby="v-pills-settings-tab" tabindex="0">...</div> + </div> +</div> +``` + +### 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 `<button>` elements for the tabs, as these are controls that trigger a dynamic change, rather than links that navigate to a new page or location. + +In line with the ARIA Authoring Practices pattern, only the currently active tab receives keyboard focus. When the JavaScript plugin is initialized, it will set `tabindex="-1"` on all inactive tab controls. Once the currently active tab has focus, the cursor keys activate the previous/next tab, with the plugin changing the [roving `tabindex`](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/) accordingly. However, note that the JavaScript plugin does not distinguish between horizontal and vertical tab lists when it comes to cursor key interactions: regardless of the tab list's orientation, both the up *and* left cursor go to the previous tab, and down *and* right cursor go to the next tab. + +{{< callout warning >}} +In general, to facilitate keyboard navigation, it's recommended to make the tab panels themselves focusable as well, unless the first element containing meaningful content inside the tab panel is already focusable. The JavaScript plugin does not try to handle this aspect—where appropriate, you'll need to explicitly make your tab panels focusable by adding `tabindex="0"` in your markup. +{{< /callout >}} + +{{< callout danger >}} +The tab JavaScript plugin **does not** support tabbed interfaces that contain dropdown menus, as these cause 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. +{{< /callout >}} + +### Using data attributes + +You can activate a tab or pill navigation without writing any JavaScript by simply specifying `data-bs-toggle="tab"` or `data-bs-toggle="pill"` on an element. Use these data attributes on `.nav-tabs` or `.nav-pills`. + +```html +<!-- Nav tabs --> +<ul class="nav nav-tabs" id="myTab" role="tablist"> + <li class="nav-item" role="presentation"> + <button class="nav-link active" id="home-tab" data-bs-toggle="tab" data-bs-target="#home" type="button" role="tab" aria-controls="home" aria-selected="true">Home</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="profile-tab" data-bs-toggle="tab" data-bs-target="#profile" type="button" role="tab" aria-controls="profile" aria-selected="false">Profile</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="messages-tab" data-bs-toggle="tab" data-bs-target="#messages" type="button" role="tab" aria-controls="messages" aria-selected="false">Messages</button> + </li> + <li class="nav-item" role="presentation"> + <button class="nav-link" id="settings-tab" data-bs-toggle="tab" data-bs-target="#settings" type="button" role="tab" aria-controls="settings" aria-selected="false">Settings</button> + </li> +</ul> + +<!-- Tab panes --> +<div class="tab-content"> + <div class="tab-pane active" id="home" role="tabpanel" aria-labelledby="home-tab" tabindex="0">...</div> + <div class="tab-pane" id="profile" role="tabpanel" aria-labelledby="profile-tab" tabindex="0">...</div> + <div class="tab-pane" id="messages" role="tabpanel" aria-labelledby="messages-tab" tabindex="0">...</div> + <div class="tab-pane" id="settings" role="tabpanel" aria-labelledby="settings-tab" tabindex="0">...</div> +</div> +``` + +### 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 +<div class="tab-content"> + <div class="tab-pane fade show active" id="home" role="tabpanel" aria-labelledby="home-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="profile" role="tabpanel" aria-labelledby="profile-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="messages" role="tabpanel" aria-labelledby="messages-tab" tabindex="0">...</div> + <div class="tab-pane fade" id="settings" role="tabpanel" aria-labelledby="settings-tab" tabindex="0">...</div> +</div> +``` + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +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') +``` + +{{< bs-table >}} +| 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). | +{{< /bs-table >}} + +### 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. + +{{< bs-table >}} +| 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. | +{{< /bs-table >}} + +```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/content/docs/5.2/components/offcanvas.md b/site/content/docs/5.2/components/offcanvas.md new file mode 100644 index 0000000..c4290ad --- /dev/null +++ b/site/content/docs/5.2/components/offcanvas.md @@ -0,0 +1,353 @@ +--- +layout: docs +title: Offcanvas +description: Build hidden sidebars into your project for navigation, shopping carts, and more with a few classes and our JavaScript plugin. +group: components +toc: true +--- + +## How it works + +Offcanvas is a sidebar component that can be toggled via JavaScript to appear from the left, right, top, or bottom edge of the viewport. Buttons or anchors are used as triggers that are attached to specific elements you toggle, and `data` attributes are used to invoke our JavaScript. + +- Offcanvas shares some of the same JavaScript code as modals. Conceptually, they are quite similar, but they are separate plugins. +- Similarly, some [source Sass](#sass) variables for offcanvas's styles and dimensions are inherited from the modal's variables. +- When shown, offcanvas includes a default backdrop that can be clicked to hide the offcanvas. +- Similar to modals, only one offcanvas can be shown at a time. + +**Heads up!** Given how CSS handles animations, you cannot use `margin` or `translate` on an `.offcanvas` element. Instead, use the class as an independent wrapping element. + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +## Examples + +### Offcanvas components + +Below is an offcanvas example that is shown by default (via `.show` on `.offcanvas`). Offcanvas includes support for a header with a close button and an optional body class for some initial `padding`. We suggest that you include offcanvas headers with dismiss actions whenever possible, or provide an explicit dismiss action. + +{{< example class="bd-example-offcanvas p-0 bg-light overflow-hidden" >}} +<div class="offcanvas offcanvas-start show" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasLabel">Offcanvas</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here. + </div> +</div> +{{< /example >}} + +### Live demo + +Use the buttons below to show and hide an offcanvas element via JavaScript that toggles the `.show` class on an element with the `.offcanvas` class. + +- `.offcanvas` hides content (default) +- `.offcanvas.show` shows content + +You can use a link with the `href` attribute, or a button with the `data-bs-target` attribute. In both cases, the `data-bs-toggle="offcanvas"` is required. + +{{< example >}} +<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample"> + Link with href +</a> +<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample"> + Button with data-bs-target +</button> + +<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasExampleLabel">Offcanvas</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + <div class=""> + Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc. + </div> + <div class="dropdown mt-3"> + <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown"> + Dropdown button + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + </ul> + </div> + </div> +</div> +{{< /example >}} + +### Body scrolling + +Scrolling the `<body>` element is disabled when an offcanvas and its backdrop are visible. Use the `data-bs-scroll` attribute to enable `<body>` scrolling. + +{{< example >}} +<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Enable body scrolling</button> + +<div class="offcanvas offcanvas-start" data-bs-scroll="true" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasScrollingLabel">Offcanvas with body scrolling</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + <p>Try scrolling the rest of the page to see this option in action.</p> + </div> +</div> +{{< /example >}} + +### Body scrolling and backdrop + +You can also enable `<body>` scrolling with a visible backdrop. + +{{< example >}} +<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">Enable both scrolling & backdrop</button> + +<div class="offcanvas offcanvas-start" data-bs-scroll="true" tabindex="-1" id="offcanvasWithBothOptions" aria-labelledby="offcanvasWithBothOptionsLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasWithBothOptionsLabel">Backdrop with scrolling</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + <p>Try scrolling the rest of the page to see this option in action.</p> + </div> +</div> +{{< /example >}} + +### Static backdrop + +When backdrop is set to static, the offcanvas will not close when clicking outside of it. + +{{< example >}} +<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#staticBackdrop" aria-controls="staticBackdrop"> + Toggle static offcanvas +</button> + +<div class="offcanvas offcanvas-start" data-bs-backdrop="static" tabindex="-1" id="staticBackdrop" aria-labelledby="staticBackdropLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="staticBackdropLabel">Offcanvas</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + <div> + I will not close if you click outside of me. + </div> + </div> +</div> +{{< /example >}} + +## Dark offcanvas + +{{< added-in "5.2.0" >}} + +Change the appearance of offcanvases with utilities to better match them to different contexts like dark navbars. Here we add `.text-bg-dark` to the `.offcanvas` and `.btn-close-white` to `.btn-close` for proper styling with a dark offcanvas. If you have dropdowns within, consider also adding `.dropdown-menu-dark` to `.dropdown-menu`. + +{{< example class="bd-example-offcanvas p-0 bg-light overflow-hidden" >}} +<div class="offcanvas offcanvas-start show text-bg-dark" tabindex="-1" id="offcanvasDark" aria-labelledby="offcanvasDarkLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasDarkLabel">Offcanvas</h5> + <button type="button" class="btn-close btn-close-white" data-bs-dismiss="offcanvasDark" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + <p>Place offcanvas content here.</p> + </div> +</div> +{{< /example >}} + +## Responsive + +{{< added-in "5.2.0" >}} + +Responsive offcanvas classes hide content outside the viewport from a specified breakpoint and down. Above that breakpoint, the contents within will behave as usual. For example, `.offcanvas-lg` hides content in an offcanvas below the `lg` breakpoint, but shows the content above the `lg` breakpoint. + +{{< example >}} +<button class="btn btn-primary d-lg-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasResponsive" aria-controls="offcanvasResponsive">Toggle offcanvas</button> + +<div class="alert alert-info d-none d-lg-block">Resize your browser to show the responsive offcanvas toggle.</div> + +<div class="offcanvas-lg offcanvas-end" tabindex="-1" id="offcanvasResponsive" aria-labelledby="offcanvasResponsiveLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasResponsiveLabel">Responsive offcanvas</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#offcanvasResponsive" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + <p class="mb-0">This is content within an <code>.offcanvas-lg</code>.</p> + </div> +</div> +{{< /example >}} + +Responsive offcanvas classes are available across for each breakpoint. + +- `.offcanvas` +- `.offcanvas-sm` +- `.offcanvas-md` +- `.offcanvas-lg` +- `.offcanvas-xl` +- `.offcanvas-xxl` + +## Placement + +There's no default placement for offcanvas components, so you must add one of the modifier classes below. + +- `.offcanvas-start` places offcanvas on the left of the viewport (shown above) +- `.offcanvas-end` places offcanvas on the right of the viewport +- `.offcanvas-top` places offcanvas on the top of the viewport +- `.offcanvas-bottom` places offcanvas on the bottom of the viewport + +Try the top, right, and bottom examples out below. + +{{< example >}} +<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">Toggle top offcanvas</button> + +<div class="offcanvas offcanvas-top" tabindex="-1" id="offcanvasTop" aria-labelledby="offcanvasTopLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasTopLabel">Offcanvas top</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + ... + </div> +</div> +{{< /example >}} + +{{< example >}} +<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">Toggle right offcanvas</button> + +<div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasRight" aria-labelledby="offcanvasRightLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasRightLabel">Offcanvas right</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body"> + ... + </div> +</div> +{{< /example >}} + +{{< example >}} +<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">Toggle bottom offcanvas</button> + +<div class="offcanvas offcanvas-bottom" tabindex="-1" id="offcanvasBottom" aria-labelledby="offcanvasBottomLabel"> + <div class="offcanvas-header"> + <h5 class="offcanvas-title" id="offcanvasBottomLabel">Offcanvas bottom</h5> + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> + </div> + <div class="offcanvas-body small"> + ... + </div> +</div> +{{< /example >}} + +## Accessibility + +Since the offcanvas panel is conceptually a modal dialog, be sure to add `aria-labelledby="..."`—referencing the offcanvas title—to `.offcanvas`. Note that you don’t need to add `role="dialog"` since we already add it via JavaScript. + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, offcanvas now uses local CSS variables on `.offcanvas` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="offcanvas-css-vars" file="scss/_offcanvas.scss" >}} + +### Sass variables + +{{< scss-docs name="offcanvas-variables" file="scss/_variables.scss" >}} + +## Usage + +The offcanvas plugin utilizes a few classes and attributes to handle the heavy lifting: + +- `.offcanvas` hides the content +- `.offcanvas.show` shows the content +- `.offcanvas-start` hides the offcanvas on the left +- `.offcanvas-end` hides the offcanvas on the right +- `.offcanvas-top` hides the offcanvas on the top +- `.offcanvas-bottom` hides the offcanvas on the bottom + +Add a dismiss button with the `data-bs-dismiss="offcanvas"` attribute, which triggers the JavaScript functionality. Be sure to use the `<button>` element with it for proper behavior across all devices. + +### Via data attributes + +#### 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`. + +#### Dismiss + +{{% js-dismiss "offcanvas" %}} + +{{< callout warning >}} +While both ways to dismiss an offcanvas are supported, keep in mind that dismissing from outside an offcanvas does not match the [ARIA Authoring Practices Guide dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/). Do this at your own risk. +{{< /callout >}} + +### Via JavaScript + +Enable manually with: + +```js +const offcanvasElementList = document.querySelectorAll('.offcanvas') +const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new bootstrap.Offcanvas(offcanvasEl)) +``` + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< bs-table "table" >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `backdrop` | boolean or the string `static` | `true` | Apply a backdrop on body while offcanvas is open. Alternatively, specify `static` for a backdrop which doesn't close the offcanvas when clicked. | +| `keyboard` | boolean | `true` | Closes the offcanvas when escape key is pressed. | +| `scroll` | boolean | `false` | Allow body scrolling while offcanvas is open. | +{{< /bs-table >}} + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +Activates your content as an offcanvas element. Accepts an optional options `object`. + +You can create an offcanvas instance with the constructor, for example: + +```js +const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas') +``` + +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `getInstance` | *Static* method which allows you to get the offcanvas instance associated with a DOM element. | +| `getOrCreateInstance` | *Static* method which allows you to get the offcanvas instance associated with a DOM element, or create a new one in case it wasn't initialized. | +| `hide` | Hides an offcanvas element. **Returns to the caller before the offcanvas element has actually been hidden** (i.e. before the `hidden.bs.offcanvas` event occurs). | +| `show` | Shows an offcanvas element. **Returns to the caller before the offcanvas element has actually been shown** (i.e. before the `shown.bs.offcanvas` event occurs). | +| `toggle` | Toggles an offcanvas element to shown or hidden. **Returns to the caller before the offcanvas element has actually been shown or hidden** (i.e. before the `shown.bs.offcanvas` or `hidden.bs.offcanvas` event occurs). | +{{< /bs-table >}} + +### Events + +Bootstrap's offcanvas class exposes a few events for hooking into offcanvas functionality. + +{{< bs-table "table" >}} +| Event type | Description | +| --- | --- | +| `hide.bs.offcanvas` | This event is fired immediately when the `hide` method has been called. | +| `hidden.bs.offcanvas` | This event is fired when an offcanvas element has been hidden from the user (will wait for CSS transitions to complete). | +| `hidePrevented.bs.offcanvas` | This event is fired when the offcanvas is shown, its backdrop is `static` and a click outside of the offcanvas is performed. The event is also fired when the escape key is pressed and the `keyboard` option is set to `false`. | +| `show.bs.offcanvas` | This event fires immediately when the `show` instance method is called. | +| `shown.bs.offcanvas` | This event is fired when an offcanvas element has been made visible to the user (will wait for CSS transitions to complete). | +{{< /bs-table >}} + +```js +const myOffcanvas = document.getElementById('myOffcanvas') +myOffcanvas.addEventListener('hidden.bs.offcanvas', event => { + // do something... +}) +``` diff --git a/site/content/docs/5.2/components/pagination.md b/site/content/docs/5.2/components/pagination.md new file mode 100644 index 0000000..7251405 --- /dev/null +++ b/site/content/docs/5.2/components/pagination.md @@ -0,0 +1,177 @@ +--- +layout: docs +title: Pagination +description: Documentation and examples for showing pagination to indicate a series of related content exists across multiple pages. +group: components +toc: true +--- + +## Overview + +We use a large block of connected links for our pagination, making links hard to miss and easily scalable—all while providing large hit areas. Pagination is built with list HTML elements so screen readers can announce the number of available links. Use a wrapping `<nav>` element to identify it as a navigation section to screen readers and other assistive technologies. + +In addition, as pages likely have more than one such navigation section, it's advisable to provide a descriptive `aria-label` for the `<nav>` to reflect its purpose. For example, if the pagination component is used to navigate between a set of search results, an appropriate label could be `aria-label="Search results pages"`. + +{{< example >}} +<nav aria-label="Page navigation example"> + <ul class="pagination"> + <li class="page-item"><a class="page-link" href="#">Previous</a></li> + <li class="page-item"><a class="page-link" href="#">1</a></li> + <li class="page-item"><a class="page-link" href="#">2</a></li> + <li class="page-item"><a class="page-link" href="#">3</a></li> + <li class="page-item"><a class="page-link" href="#">Next</a></li> + </ul> +</nav> +{{< /example >}} + +## Working with icons + +Looking to use an icon or symbol in place of text for some pagination links? Be sure to provide proper screen reader support with `aria` attributes. + +{{< example >}} +<nav aria-label="Page navigation example"> + <ul class="pagination"> + <li class="page-item"> + <a class="page-link" href="#" aria-label="Previous"> + <span aria-hidden="true">«</span> + </a> + </li> + <li class="page-item"><a class="page-link" href="#">1</a></li> + <li class="page-item"><a class="page-link" href="#">2</a></li> + <li class="page-item"><a class="page-link" href="#">3</a></li> + <li class="page-item"> + <a class="page-link" href="#" aria-label="Next"> + <span aria-hidden="true">»</span> + </a> + </li> + </ul> +</nav> +{{< /example >}} + +## Disabled and active states + +Pagination links are customizable for different circumstances. Use `.disabled` for links that appear un-clickable and `.active` to indicate the current page. + +While the `.disabled` class uses `pointer-events: none` to _try_ to disable the link functionality of `<a>`s, that CSS property is not yet standardized and doesn't account for keyboard navigation. As such, you should always add `tabindex="-1"` on disabled links and use custom JavaScript to fully disable their functionality. + +{{< example >}} +<nav aria-label="..."> + <ul class="pagination"> + <li class="page-item disabled"> + <a class="page-link">Previous</a> + </li> + <li class="page-item"><a class="page-link" href="#">1</a></li> + <li class="page-item active" aria-current="page"> + <a class="page-link" href="#">2</a> + </li> + <li class="page-item"><a class="page-link" href="#">3</a></li> + <li class="page-item"> + <a class="page-link" href="#">Next</a> + </li> + </ul> +</nav> +{{< /example >}} + +You can optionally swap out active or disabled anchors for `<span>`, or omit the anchor in the case of the prev/next arrows, to remove click functionality and prevent keyboard focus while retaining intended styles. + +{{< example >}} +<nav aria-label="..."> + <ul class="pagination"> + <li class="page-item disabled"> + <span class="page-link">Previous</span> + </li> + <li class="page-item"><a class="page-link" href="#">1</a></li> + <li class="page-item active" aria-current="page"> + <span class="page-link">2</span> + </li> + <li class="page-item"><a class="page-link" href="#">3</a></li> + <li class="page-item"> + <a class="page-link" href="#">Next</a> + </li> + </ul> +</nav> +{{< /example >}} + +## Sizing + +Fancy larger or smaller pagination? Add `.pagination-lg` or `.pagination-sm` for additional sizes. + +{{< example >}} +<nav aria-label="..."> + <ul class="pagination pagination-lg"> + <li class="page-item active" aria-current="page"> + <span class="page-link">1</span> + </li> + <li class="page-item"><a class="page-link" href="#">2</a></li> + <li class="page-item"><a class="page-link" href="#">3</a></li> + </ul> +</nav> +{{< /example >}} + +{{< example >}} +<nav aria-label="..."> + <ul class="pagination pagination-sm"> + <li class="page-item active" aria-current="page"> + <span class="page-link">1</span> + </li> + <li class="page-item"><a class="page-link" href="#">2</a></li> + <li class="page-item"><a class="page-link" href="#">3</a></li> + </ul> +</nav> +{{< /example >}} + +## Alignment + +Change the alignment of pagination components with [flexbox utilities]({{< docsref "/utilities/flex" >}}). For example, with `.justify-content-center`: + +{{< example >}} +<nav aria-label="Page navigation example"> + <ul class="pagination justify-content-center"> + <li class="page-item disabled"> + <a class="page-link">Previous</a> + </li> + <li class="page-item"><a class="page-link" href="#">1</a></li> + <li class="page-item"><a class="page-link" href="#">2</a></li> + <li class="page-item"><a class="page-link" href="#">3</a></li> + <li class="page-item"> + <a class="page-link" href="#">Next</a> + </li> + </ul> +</nav> +{{< /example >}} + +Or with `.justify-content-end`: + +{{< example >}} +<nav aria-label="Page navigation example"> + <ul class="pagination justify-content-end"> + <li class="page-item disabled"> + <a class="page-link">Previous</a> + </li> + <li class="page-item"><a class="page-link" href="#">1</a></li> + <li class="page-item"><a class="page-link" href="#">2</a></li> + <li class="page-item"><a class="page-link" href="#">3</a></li> + <li class="page-item"> + <a class="page-link" href="#">Next</a> + </li> + </ul> +</nav> +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, pagination now uses local CSS variables on `.pagination` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="pagination-css-vars" file="scss/_pagination.scss" >}} + +### Sass variables + +{{< scss-docs name="pagination-variables" file="scss/_variables.scss" >}} + +### Sass mixins + +{{< scss-docs name="pagination-mixin" file="scss/mixins/_pagination.scss" >}} diff --git a/site/content/docs/5.2/components/placeholders.md b/site/content/docs/5.2/components/placeholders.md new file mode 100644 index 0000000..4de4057 --- /dev/null +++ b/site/content/docs/5.2/components/placeholders.md @@ -0,0 +1,145 @@ +--- +layout: docs +title: Placeholders +description: Use loading placeholders for your components or pages to indicate something may still be loading. +group: components +toc: true +added: "5.1" +--- + +## About + +Placeholders can be used to enhance the experience of your application. They're built only with HTML and CSS, meaning you don't need any JavaScript to create them. You will, however, need some custom JavaScript to toggle their visibility. Their appearance, color, and sizing can be easily customized with our utility classes. + +## Example + +In the example below, we take a typical card component and recreate it with placeholders applied to create a "loading card". Size and proportions are the same between the two. + +<div class="bd-example bd-example-placeholder-cards d-flex justify-content-around"> +<div class="card"> + {{< placeholder width="100%" height="180" class="card-img-top" text="false" background="#20c997" >}} + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> + +<div class="card" aria-hidden="true"> + {{< placeholder width="100%" height="180" class="card-img-top" text="false" >}} + <div class="card-body"> + <div class="h5 card-title placeholder-glow"> + <span class="placeholder col-6"></span> + </div> + <p class="card-text placeholder-glow"> + <span class="placeholder col-7"></span> + <span class="placeholder col-4"></span> + <span class="placeholder col-4"></span> + <span class="placeholder col-6"></span> + <span class="placeholder col-8"></span> + </p> + <a href="#" tabindex="-1" class="btn btn-primary disabled placeholder col-6"></a> + </div> +</div> +</div> + +```html +<div class="card"> + <img src="..." class="card-img-top" alt="..."> + + <div class="card-body"> + <h5 class="card-title">Card title</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + <a href="#" class="btn btn-primary">Go somewhere</a> + </div> +</div> + +<div class="card" aria-hidden="true"> + <img src="..." class="card-img-top" alt="..."> + <div class="card-body"> + <h5 class="card-title placeholder-glow"> + <span class="placeholder col-6"></span> + </h5> + <p class="card-text placeholder-glow"> + <span class="placeholder col-7"></span> + <span class="placeholder col-4"></span> + <span class="placeholder col-4"></span> + <span class="placeholder col-6"></span> + <span class="placeholder col-8"></span> + </p> + <a href="#" tabindex="-1" class="btn btn-primary disabled placeholder col-6"></a> + </div> +</div> +``` + +## How it works + +Create placeholders with the `.placeholder` class and a grid column class (e.g., `.col-6`) to set the `width`. They can replace the text inside an element or be added as a modifier class to an existing component. + +We apply additional styling to `.btn`s via `::before` to ensure the `height` is respected. You may extend this pattern for other situations as needed, or add a ` ` within the element to reflect the height when actual text is rendered in its place. + +{{< example >}} +<p aria-hidden="true"> + <span class="placeholder col-6"></span> +</p> + +<a href="#" tabindex="-1" class="btn btn-primary disabled placeholder col-4" aria-hidden="true"></a> +{{< /example >}} + +{{< callout info >}} +The use of `aria-hidden="true"` only indicates that the element should be hidden to screen readers. The *loading* behavior of the placeholder depends on how authors will actually use the placeholder styles, how they plan to update things, etc. Some JavaScript code may be needed to *swap* the state of the placeholder and inform AT users of the update. +{{< /callout >}} + +### Width + +You can change the `width` through grid column classes, width utilities, or inline styles. + +{{< example >}} +<span class="placeholder col-6"></span> +<span class="placeholder w-75"></span> +<span class="placeholder" style="width: 25%;"></span> +{{< /example >}} + +### Color + +By default, the `placeholder` uses `currentColor`. This can be overridden with a custom color or utility class. + +{{< example >}} +<span class="placeholder col-12"></span> +{{< placeholders.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<span class="placeholder col-12 bg-{{ .name }}"></span> +{{- end -}} +{{< /placeholders.inline >}} +{{< /example >}} + +### Sizing + +The size of `.placeholder`s are based on the typographic style of the parent element. Customize them with sizing modifiers: `.placeholder-lg`, `.placeholder-sm`, or `.placeholder-xs`. + +{{< example >}} +<span class="placeholder col-12 placeholder-lg"></span> +<span class="placeholder col-12"></span> +<span class="placeholder col-12 placeholder-sm"></span> +<span class="placeholder col-12 placeholder-xs"></span> +{{< /example >}} + +### Animation + +Animate placeholders with `.placeholder-glow` or `.placeholder-wave` to better convey the perception of something being _actively_ loaded. + +{{< example >}} +<p class="placeholder-glow"> + <span class="placeholder col-12"></span> +</p> + +<p class="placeholder-wave"> + <span class="placeholder col-12"></span> +</p> +{{< /example >}} + +## Sass + +### Variables + +{{< scss-docs name="placeholders" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/components/popovers.md b/site/content/docs/5.2/components/popovers.md new file mode 100644 index 0000000..9726c30 --- /dev/null +++ b/site/content/docs/5.2/components/popovers.md @@ -0,0 +1,284 @@ +--- +layout: docs +title: Popovers +description: Documentation and examples for adding Bootstrap popovers, like those found in iOS, to any element on your site. +group: components +toc: true +--- + +## Overview + +Things to know when using the popover plugin: + +- Popovers rely on the third party library [Popper](https://popper.js.org/) for positioning. You must include [popper.min.js]({{< param "cdn.popper" >}}) before `bootstrap.js`, or use one `bootstrap.bundle.min.js` which contains Popper. +- Popovers require the [popover plugin]({{< docsref "/components/popovers" >}}) as a dependency. +- Popovers are opt-in for performance reasons, so **you must initialize them yourself**. +- Zero-length `title` and `content` values will never show a popover. +- Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc). +- Triggering popovers on hidden elements will not work. +- Popovers for `.disabled` or `disabled` elements must be triggered on a wrapper element. +- When triggered from anchors that wrap across multiple lines, popovers will be centered between the anchors' overall width. Use `.text-nowrap` on your `<a>`s to avoid this behavior. +- Popovers must be hidden before their corresponding elements have been removed from the DOM. +- Popovers can be triggered thanks to an element inside a shadow DOM. + +{{< callout info >}} +{{< partial "callout-info-sanitizer.md" >}} +{{< /callout >}} + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +Keep reading to see how popovers work with some examples. + +## Examples + +### Enable popovers + +As mentioned above, you must initialize popovers before they can be used. One way to initialize all popovers on a page would be to select them by their `data-bs-toggle` attribute, like so: + +```js +const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]') +const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl)) +``` + +### Live demo + +We use JavaScript similar to the snippet above to render the following live popover. Titles are set via `data-bs-title` and body content is set via `data-bs-content`. + +{{< callout warning >}} +{{< partial "callout-warning-data-bs-title-vs-title.md" >}} +{{< /callout >}} + +{{< example stackblitz_add_js="true" >}} +<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" data-bs-title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button> +{{< /example >}} + +### Four directions + +Four options are available: top, right, bottom, and left. Directions are mirrored when using Bootstrap in RTL. Set `data-bs-placement` to change the direction. + +{{< example stackblitz_add_js="true" >}} +<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover"> + Popover on top +</button> +<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover"> + Popover on right +</button> +<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover"> + Popover on bottom +</button> +<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover"> + Popover on left +</button> +{{< /example >}} + +### Custom `container` + +When you have some styles on a parent element that interfere with a popover, you'll want to specify a custom `container` so that the popover's HTML appears within that element instead. This is common in responsive tables, input groups, and the like. + +```js +const popover = new bootstrap.Popover('.example-popover', { + container: 'body' +}) +``` + +Another situation where you'll want to set an explicit custom `container` are popovers inside a [modal dialog]({{< docsref "/components/modal" >}}), to make sure that the popover itself is appended to the modal. This is particularly important for popovers that contain interactive elements – modal dialogs will trap focus, so unless the popover is a child element of the modal, users won't be able to focus or activate these interactive elements. + +```js +const popover = new bootstrap.Popover('.example-popover', { + container: '.modal-body' +}) +``` + +### Custom popovers + +{{< added-in "5.2.0" >}} + +You can customize the appearance of popovers using [CSS variables](#variables). We set a custom class with `data-bs-custom-class="custom-popover"` to scope our custom appearance and use it to override some of the local CSS variables. + +{{< scss-docs name="custom-popovers" file="site/assets/scss/_component-examples.scss" >}} + +{{< example class="custom-popover-demo" stackblitz_add_js="true" >}} +<button type="button" class="btn btn-secondary" + data-bs-toggle="popover" data-bs-placement="right" + data-bs-custom-class="custom-popover" + data-bs-title="Custom popover" + data-bs-content="This popover is themed via CSS variables."> + Custom popover +</button> +{{< /example >}} + +### Dismiss on next click + +Use the `focus` trigger to dismiss popovers on the user's next click of a different element than the toggle element. + +{{< callout danger >}} +#### Specific markup required for dismiss-on-next-click + +For proper cross-browser and cross-platform behavior, you must use the `<a>` tag, _not_ the `<button>` tag, and you also must include a [`tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute. +{{< /callout >}} + +{{< example stackblitz_add_js="true" >}} +<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" data-bs-title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a> +{{< /example >}} + +```js +const popover = new bootstrap.Popover('.popover-dismiss', { + trigger: 'focus' +}) +``` + +### Disabled elements + +Elements with the `disabled` attribute aren't interactive, meaning users cannot hover or click them to trigger a popover (or tooltip). As a workaround, you'll want to trigger the popover from a wrapper `<div>` or `<span>`, ideally made keyboard-focusable using `tabindex="0"`. + +For disabled popover triggers, you may also prefer `data-bs-trigger="hover focus"` so that the popover appears as immediate visual feedback to your users as they may not expect to _click_ on a disabled element. + +{{< example stackblitz_add_js="true" >}} +<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover"> + <button class="btn btn-primary" type="button" disabled>Disabled button</button> +</span> +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap’s evolving CSS variables approach, popovers now use local CSS variables on `.popover` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="popover-css-vars" file="scss/_popover.scss" >}} + +### Sass variables + +{{< scss-docs name="popover-variables" file="scss/_variables.scss" >}} + +## Usage + +Enable popovers via JavaScript: + +```js +const exampleEl = document.getElementById('example') +const popover = new bootstrap.Popover(exampleEl, options) +``` + +{{< callout warning >}} +### Making popovers work for keyboard and assistive technology users + +To allow keyboard users to activate your popovers, you should only add them to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). Although arbitrary HTML elements (such as `<span>`s) can be made focusable by adding the `tabindex="0"` attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users, and most assistive technologies currently do not announce the popover's content in this situation. Additionally, do not rely solely on `hover` as the trigger for your popovers, as this will make them impossible to trigger for keyboard users. + +While you can insert rich, structured HTML in popovers with the `html` option, we strongly recommend that you avoid adding an excessive amount of content. The way popovers currently work is that, once displayed, their content is tied to the trigger element with the `aria-describedby` attribute. As a result, the entirety of the popover's content will be announced to assistive technology users as one long, uninterrupted stream. + +Additionally, while it is possible to also include interactive controls (such as form elements or links) in your popover (by adding these elements to the `allowList` of allowed attributes and tags), be aware that currently the popover does not manage keyboard focus order. When a keyboard user opens a popover, focus remains on the triggering element, and as the popover usually does not immediately follow the trigger in the document's structure, there is no guarantee that moving forward/pressing <kbd>TAB</kbd> will move a keyboard user into the popover itself. In short, simply adding interactive controls to a popover is likely to make these controls unreachable/unusable for keyboard users and users of assistive technologies, or at the very least make for an illogical overall focus order. In these cases, consider using a modal dialog instead. +{{< /callout >}} + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< callout warning >}} +Note that for security reasons the `sanitize`, `sanitizeFn`, and `allowList` options cannot be supplied using data attributes. +{{< /callout >}} + +{{< bs-table "table" >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `allowList` | object | [Default value]({{< docsref "/getting-started/javascript#sanitizer" >}}) | Object which contains allowed attributes and tags. | +| `animation` | boolean | `true` | Apply a CSS fade transition to the popover. | +| `boundary` | string, element | `'clippingParents'` | Overflow constraint boundary of the popover (applies only to Popper's preventOverflow modifier). By default, it's `'clippingParents'` and can accept an HTMLElement reference (via JavaScript only). For more information refer to Popper's [detectOverflow docs](https://popper.js.org/docs/v2/utils/detect-overflow/#boundary). | +| `container` | string, element, false | `false` | Appends the popover to a specific element. Example: `container: 'body'`. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize. | +| `content` | string, element, function | `''` | Default content value if `data-bs-content` attribute isn't present. If a function is given, it will be called with its `this` reference set to the element that the popover is attached to. | +| `customClass` | string, function | `''` | Add classes to the popover when it is shown. Note that these classes will be added in addition to any classes specified in the template. To add multiple classes, separate them with spaces: `'class-1 class-2'`. You can also pass a function that should return a single string containing additional class names. | +| `delay` | number, object | `0` | Delay showing and hiding the popover (ms)—doesn't apply to manual trigger type. If a number is supplied, delay is applied to both hide/show. Object structure is: `delay: { "show": 500, "hide": 100 }`. | +| `fallbackPlacements` | string, array | `['top', 'right', 'bottom', 'left']` | Define fallback placements by providing a list of placements in array (in order of preference). For more information refer to Popper's [behavior docs](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements). | +| `html` | boolean | `false` | Allow HTML in the popover. If true, HTML tags in the popover's `title` will be rendered in the popover. If false, `innerText` property will be used to insert content into the DOM. Use text if you're worried about XSS attacks. | +| `offset` | number, string, function | `[0, 0]` | Offset of the popover relative to its target. You can pass a string in data attributes with comma separated values like: `data-bs-offset="10,20"`. When a function is used to determine the offset, it is called with an object containing the popper placement, the reference, and popper rects as its first argument. The triggering element DOM node is passed as the second argument. The function must return an array with two numbers: [skidding](https://popper.js.org/docs/v2/modifiers/offset/#skidding-1), [distance](https://popper.js.org/docs/v2/modifiers/offset/#distance-1). For more information refer to Popper's [offset docs](https://popper.js.org/docs/v2/modifiers/offset/#options). | +| `placement` | string, function | `'top'` | How to position the popover: auto, top, bottom, left, right. When `auto` is specified, it will dynamically reorient the popover. When a function is used to determine the placement, it is called with the popover DOM node as its first argument and the triggering element DOM node as its second. The `this` context is set to the popover instance. | +| `popperConfig` | null, object, function | `null` | To change Bootstrap's default Popper config, see [Popper's configuration](https://popper.js.org/docs/v2/constructors/#options). When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper. | +| `sanitize` | boolean | `true` | Enable or disable the sanitization. If activated `'template'`, `'content'` and `'title'` options will be sanitized. | +| `sanitizeFn` | null, function | `null` | Here you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization. | +| `selector` | string, false | `false` | If a selector is provided, popover objects will be delegated to the specified targets. In practice, this is used to also apply popovers to dynamically added DOM elements (`jQuery.on` support). See [this issue]({{< param repo >}}/issues/4215) and [an informative example](https://codepen.io/Johann-S/pen/djJYPb). **Note**: `title` attribute must not be used as a selector. | +| `template` | string | `'<div class="popover" role="popover"><div class="popover-arrow"></div><div class="popover-inner"></div></div>'` | Base HTML to use when creating the popover. The popover's `title` will be injected into the `.popover-inner`. `.popover-arrow` will become the popover's arrow. The outermost wrapper element should have the `.popover` class and `role="popover"`. | +| `title` | string, element, function | `''` | Default title value if `title` attribute isn't present. If a function is given, it will be called with its `this` reference set to the element that the popover is attached to. | +| `trigger` | string | `'hover focus'` | How popover is triggered: click, hover, focus, manual. You may pass multiple triggers; separate them with a space. `'manual'` indicates that the popover will be triggered programmatically via the `.popover('show')`, `.popover('hide')` and `.popover('toggle')` methods; this value cannot be combined with any other trigger. `'hover'` on its own will result in popovers that cannot be triggered via the keyboard, and should only be used if alternative methods for conveying the same information for keyboard users is present. | +{{< /bs-table >}} + +{{< callout info >}} +#### Data attributes for individual popovers + +Options for individual popovers can alternatively be specified through the use of data attributes, as explained above. +{{< /callout >}} + +#### Using function with `popperConfig` + +```js +const popover = new bootstrap.Popover(element, { + popperConfig(defaultBsPopperConfig) { + // const newPopperConfig = {...} + // use defaultBsPopperConfig if needed... + // return newPopperConfig + } +}) +``` + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `disable` | Removes the ability for an element's popover to be shown. The popover will only be able to be shown if it is re-enabled. | +| `dispose` | Hides and destroys an element's popover (Removes stored data on the DOM element). Popovers that use delegation (which are created using [the `selector` option](#options)) cannot be individually destroyed on descendant trigger elements. | +| `enable` | Gives an element's popover the ability to be shown. **Popovers are enabled by default.** | +| `getInstance` | _Static_ method which allows you to get the popover instance associated with a DOM element. | +| `getOrCreateInstance` | *Static* method which allows you to get the popover instance associated with a DOM element, or create a new one in case it wasn't initialized. | +| `hide` | Hides an element's popover. **Returns to the caller before the popover has actually been hidden** (i.e. before the `hidden.bs.popover` event occurs). This is considered a "manual" triggering of the popover. | +| `setContent` | Gives a way to change the popover's content after its initialization. | +| `show` | Reveals an element's popover. **Returns to the caller before the popover has actually been shown** (i.e. before the `shown.bs.popover` event occurs). This is considered a "manual" triggering of the popover. Popovers whose title and content are both zero-length are never displayed. | +| `toggle` | Toggles an element's popover. **Returns to the caller before the popover has actually been shown or hidden** (i.e. before the `shown.bs.popover` or `hidden.bs.popover` event occurs). This is considered a "manual" triggering of the popover. | +| `toggleEnabled` | Toggles the ability for an element's popover to be shown or hidden. | +| `update` | Updates the position of an element's popover. | +{{< /bs-table >}} + + +```js +// getOrCreateInstance example +const popover = bootstrap.Popover.getOrCreateInstance('#example') // Returns a Bootstrap popover instance + +// setContent example +myPopover.setContent({ + '.popover-header': 'another title', + '.popover-body': 'another content' +}) + +``` + +{{< callout info >}} +The `setContent` method accepts an `object` argument, where each property-key is a valid `string` selector within the popover template, and each related property-value can be `string` | `element` | `function` | `null` +{{< /callout >}} + +### Events + +{{< bs-table >}} +| Event | Description | +| --- | --- | +| `hide.bs.popover` | This event is fired immediately when the `hide` instance method has been called. | +| `hidden.bs.popover` | This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete). | +| `inserted.bs.popover` | This event is fired after the `show.bs.popover` event when the popover template has been added to the DOM. | +| `show.bs.popover` | This event fires immediately when the `show` instance method is called. | +| `shown.bs.popover` | This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete). | +{{< /bs-table >}} + +```js +const myPopoverTrigger = document.getElementById('myPopover') +myPopoverTrigger.addEventListener('hidden.bs.popover', () => { + // do something... +}) +``` diff --git a/site/content/docs/5.2/components/progress.md b/site/content/docs/5.2/components/progress.md new file mode 100644 index 0000000..aa79368 --- /dev/null +++ b/site/content/docs/5.2/components/progress.md @@ -0,0 +1,154 @@ +--- +layout: docs +title: Progress +description: Documentation and examples for using Bootstrap custom progress bars featuring support for stacked bars, animated backgrounds, and text labels. +group: components +toc: true +--- + +## How it works + +Progress components are built with two HTML elements, some CSS to set the width, and a few attributes. We don't use [the HTML5 `<progress>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress), ensuring you can stack progress bars, animate them, and place text labels over them. + +- We use the `.progress` as a wrapper to indicate the max value of the progress bar. +- We use the inner `.progress-bar` to indicate the progress so far. +- The `.progress-bar` requires an inline style, utility class, or custom CSS to set their width. +- The `.progress-bar` also requires some `role` and `aria` attributes to make it accessible, including an accessible name (using `aria-label`, `aria-labelledby`, or similar). + +Put that all together, and you have the following examples. + +{{< example >}} +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Basic example" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 25%" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 50%" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 75%" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 100%" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100"></div> +</div> +{{< /example >}} + +Bootstrap provides a handful of [utilities for setting width]({{< docsref "/utilities/sizing" >}}). Depending on your needs, these may help with quickly configuring progress. + +{{< example >}} +<div class="progress"> + <div class="progress-bar w-75" role="progressbar" aria-label="Basic example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"></div> +</div> +{{< /example >}} + +## Labels + +Add labels to your progress bars by placing text within the `.progress-bar`. + +{{< example >}} +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Example with label" style="width: 25%;" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">25%</div> +</div> +{{< /example >}} + +## Height + +We only set a `height` value on the `.progress`, so if you change that value the inner `.progress-bar` will automatically resize accordingly. + +{{< example >}} +<div class="progress" style="height: 1px;"> + <div class="progress-bar" role="progressbar" aria-label="Example 1px high" style="width: 25%;" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress" style="height: 20px;"> + <div class="progress-bar" role="progressbar" aria-label="Example 20px high" style="width: 25%;" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div> +</div> +{{< /example >}} + +## Backgrounds + +Use background utility classes to change the appearance of individual progress bars. + +{{< example >}} +<div class="progress"> + <div class="progress-bar bg-success" role="progressbar" aria-label="Success example" style="width: 25%" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar bg-info" role="progressbar" aria-label="Info example" style="width: 50%" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar bg-warning" role="progressbar" aria-label="Warning example" style="width: 75%" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar bg-danger" role="progressbar" aria-label="Danger example" style="width: 100%" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100"></div> +</div> +{{< /example >}} + +{{< callout info >}} +{{< partial "callout-warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## Multiple bars + +Include multiple progress bars in a progress component if you need. + +{{< example >}} +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Segment one" style="width: 15%" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100"></div> + <div class="progress-bar bg-success" role="progressbar" aria-label="Segment two" style="width: 30%" aria-valuenow="30" aria-valuemin="0" aria-valuemax="100"></div> + <div class="progress-bar bg-info" role="progressbar" aria-label="Segment three" style="width: 20%" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100"></div> +</div> +{{< /example >}} + +## Striped + +Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gradient over the progress bar's background color. + +{{< example >}} +<div class="progress"> + <div class="progress-bar progress-bar-striped" role="progressbar" aria-label="Default striped example" style="width: 10%" aria-valuenow="10" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar progress-bar-striped bg-success" role="progressbar" aria-label="Success striped example" style="width: 25%" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar progress-bar-striped bg-info" role="progressbar" aria-label="Info striped example" style="width: 50%" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar progress-bar-striped bg-warning" role="progressbar" aria-label="Warning striped example" style="width: 75%" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"></div> +</div> +<div class="progress"> + <div class="progress-bar progress-bar-striped bg-danger" role="progressbar" aria-label="Danger striped example" style="width: 100%" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100"></div> +</div> +{{< /example >}} + +## Animated stripes + +The striped gradient can also be animated. Add `.progress-bar-animated` to `.progress-bar` to animate the stripes right to left via CSS3 animations. + +{{< example >}} +<div class="progress"> + <div class="progress-bar progress-bar-striped progress-bar-animated" role="progressbar" aria-label="Animated striped example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100" style="width: 75%"></div> +</div> +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, progress bars now use local CSS variables on `.progress` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="progress-css-vars" file="scss/_progress.scss" >}} + +### Sass variables + +{{< scss-docs name="progress-variables" file="scss/_variables.scss" >}} + +### Keyframes + +Used for creating the CSS animations for `.progress-bar-animated`. Included in `scss/_progress-bar.scss`. + +{{< scss-docs name="progress-keyframes" file="scss/_progress.scss" >}} diff --git a/site/content/docs/5.2/components/scrollspy.md b/site/content/docs/5.2/components/scrollspy.md new file mode 100644 index 0000000..53e3fa0 --- /dev/null +++ b/site/content/docs/5.2/components/scrollspy.md @@ -0,0 +1,427 @@ +--- +layout: docs +title: Scrollspy +description: Automatically update Bootstrap navigation or list group components based on scroll position to indicate which link is currently active in the viewport. +group: components +toc: true +--- + +## How it works + +Scrollspy toggles the `.active` class on anchor (`<a>`) 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. + +- 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 `<body>` or a custom element with a set `height` and `overflow-y: scroll`. + +- On the scrollable container, add `data-bs-spy="scroll"` and `data-bs-target="#navId"` where `navId` is the unique `id` of the associated navigation. Be sure to also include a `tabindex="0"` to ensure keyboard access. + +- As you scroll the "spied" container, an `.active` class is added and removed from anchor links within the associated navigation. Links must have resolvable `id` targets, otherwise they're ignored. For example, a `<a href="#home">home</a>` must correspond to something in the DOM like `<div id="home"></div>` + +- Target elements that are not visible will be ignored. See the [Non-visible elements](#non-visible-elements) section below. + +## Examples + +### Navbar + +Scroll the area below the navbar and watch the active class change. Open the dropdown menu and watch the dropdown items be highlighted as well. + +<div class="bd-example"> + <nav id="navbar-example2" class="navbar bg-light px-3 mb-3"> + <a class="navbar-brand" href="#">Navbar</a> + <ul class="nav nav-pills"> + <li class="nav-item"> + <a class="nav-link" href="#scrollspyHeading1">First</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#scrollspyHeading2">Second</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Dropdown</a> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#scrollspyHeading3">Third</a></li> + <li><a class="dropdown-item" href="#scrollspyHeading4">Fourth</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#scrollspyHeading5">Fifth</a></li> + </ul> + </li> + </ul> + </nav> + <div class="scrollspy-example bg-light p-3 rounded-2" data-bs-spy="scroll" data-bs-target="#navbar-example2" data-bs-root-margin="0px 0px -40%" data-bs-smooth-scroll="true" tabindex="0"> + <h4 id="scrollspyHeading1">First heading</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="scrollspyHeading2">Second heading</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="scrollspyHeading3">Third heading</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="scrollspyHeading4">Fourth heading</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="scrollspyHeading5">Fifth heading</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + </div> +</div> + +```html +<nav id="navbar-example2" class="navbar bg-light px-3 mb-3"> + <a class="navbar-brand" href="#">Navbar</a> + <ul class="nav nav-pills"> + <li class="nav-item"> + <a class="nav-link" href="#scrollspyHeading1">First</a> + </li> + <li class="nav-item"> + <a class="nav-link" href="#scrollspyHeading2">Second</a> + </li> + <li class="nav-item dropdown"> + <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Dropdown</a> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#scrollspyHeading3">Third</a></li> + <li><a class="dropdown-item" href="#scrollspyHeading4">Fourth</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#scrollspyHeading5">Fifth</a></li> + </ul> + </li> + </ul> +</nav> +<div data-bs-spy="scroll" data-bs-target="#navbar-example2" data-bs-root-margin="0px 0px -40%" data-bs-smooth-scroll="true" class="scrollspy-example bg-light p-3 rounded-2" tabindex="0"> + <h4 id="scrollspyHeading1">First heading</h4> + <p>...</p> + <h4 id="scrollspyHeading2">Second heading</h4> + <p>...</p> + <h4 id="scrollspyHeading3">Third heading</h4> + <p>...</p> + <h4 id="scrollspyHeading4">Fourth heading</h4> + <p>...</p> + <h4 id="scrollspyHeading5">Fifth heading</h4> + <p>...</p> +</div> +``` + +### Nested nav + +Scrollspy also works with nested `.nav`s. If a nested `.nav` is `.active`, its parents will also be `.active`. Scroll the area next to the navbar and watch the active class change. + +<div class="bd-example"> + <div class="row"> + <div class="col-4"> + <nav id="navbar-example3" class="h-100 flex-column align-items-stretch pe-4 border-end"> + <nav class="nav nav-pills flex-column"> + <a class="nav-link" href="#item-1">Item 1</a> + <nav class="nav nav-pills flex-column"> + <a class="nav-link ms-3 my-1" href="#item-1-1">Item 1-1</a> + <a class="nav-link ms-3 my-1" href="#item-1-2">Item 1-2</a> + </nav> + <a class="nav-link" href="#item-2">Item 2</a> + <a class="nav-link" href="#item-3">Item 3</a> + <nav class="nav nav-pills flex-column"> + <a class="nav-link ms-3 my-1" href="#item-3-1">Item 3-1</a> + <a class="nav-link ms-3 my-1" href="#item-3-2">Item 3-2</a> + </nav> + </nav> + </nav> + </div> + <div class="col-8"> + <div data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-smooth-scroll="true" class="scrollspy-example-2" tabindex="0"> + <div id="item-1"> + <h4>Item 1</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <p>Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.</p> + </div> + <div id="item-1-1"> + <h5>Item 1-1</h5> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <p>Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.</p> + </div> + <div id="item-1-2"> + <h5>Item 1-2</h5> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <p>Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.</p> + </div> + <div id="item-2"> + <h4>Item 2</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <p>Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.</p> + </div> + <div id="item-3"> + <h4>Item 3</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <p>Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.</p> + </div> + <div id="item-3-1"> + <h5>Item 3-1</h5> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <p>Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.</p> + </div> + <div id="item-3-2"> + <h5>Item 3-2</h5> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <p>Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.</p> + </div> + </div> + </div> + </div> +</div> + +```html +<div class="row"> + <div class="col-4"> + <nav id="navbar-example3" class="h-100 flex-column align-items-stretch pe-4 border-end"> + <nav class="nav nav-pills flex-column"> + <a class="nav-link" href="#item-1">Item 1</a> + <nav class="nav nav-pills flex-column"> + <a class="nav-link ms-3 my-1" href="#item-1-1">Item 1-1</a> + <a class="nav-link ms-3 my-1" href="#item-1-2">Item 1-2</a> + </nav> + <a class="nav-link" href="#item-2">Item 2</a> + <a class="nav-link" href="#item-3">Item 3</a> + <nav class="nav nav-pills flex-column"> + <a class="nav-link ms-3 my-1" href="#item-3-1">Item 3-1</a> + <a class="nav-link ms-3 my-1" href="#item-3-2">Item 3-2</a> + </nav> + </nav> + </nav> + </div> + + <div class="col-8"> + <div data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-smooth-scroll="true" class="scrollspy-example-2" tabindex="0"> + <div id="item-1"> + <h4>Item 1</h4> + <p>...</p> + </div> + <div id="item-1-1"> + <h5>Item 1-1</h5> + <p>...</p> + </div> + <div id="item-1-2"> + <h5>Item 1-2</h5> + <p>...</p> + </div> + <div id="item-2"> + <h4>Item 2</h4> + <p>...</p> + </div> + <div id="item-3"> + <h4>Item 3</h4> + <p>...</p> + </div> + <div id="item-3-1"> + <h5>Item 3-1</h5> + <p>...</p> + </div> + <div id="item-3-2"> + <h5>Item 3-2</h5> + <p>...</p> + </div> + </div> + </div> +</div> +``` + +### List group + +Scrollspy also works with `.list-group`s. Scroll the area next to the list group and watch the active class change. + +<div class="bd-example"> + <div class="row"> + <div class="col-4"> + <div id="list-example" class="list-group"> + <a class="list-group-item list-group-item-action" href="#list-item-1">Item 1</a> + <a class="list-group-item list-group-item-action" href="#list-item-2">Item 2</a> + <a class="list-group-item list-group-item-action" href="#list-item-3">Item 3</a> + <a class="list-group-item list-group-item-action" href="#list-item-4">Item 4</a> + </div> + </div> + <div class="col-8"> + <div data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0"> + <h4 id="list-item-1">Item 1</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="list-item-2">Item 2</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="list-item-3">Item 3</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="list-item-4">Item 4</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + </div> + </div> + </div> +</div> + +```html +<div class="row"> + <div class="col-4"> + <div id="list-example" class="list-group"> + <a class="list-group-item list-group-item-action" href="#list-item-1">Item 1</a> + <a class="list-group-item list-group-item-action" href="#list-item-2">Item 2</a> + <a class="list-group-item list-group-item-action" href="#list-item-3">Item 3</a> + <a class="list-group-item list-group-item-action" href="#list-item-4">Item 4</a> + </div> + </div> + <div class="col-8"> + <div data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0"> + <h4 id="list-item-1">Item 1</h4> + <p>...</p> + <h4 id="list-item-2">Item 2</h4> + <p>...</p> + <h4 id="list-item-3">Item 3</h4> + <p>...</p> + <h4 id="list-item-4">Item 4</h4> + <p>...</p> + </div> + </div> +</div> +``` + +### Simple anchors + +Scrollspy is not limited to nav components and list groups, so it will work on any `<a>` anchor elements in the current document. Scroll the area and watch the `.active` class change. + +<div class="bd-example"> + <div class="row"> + <div class="col-4"> + <div id="simple-list-example" class="d-flex flex-column gap-2 simple-list-example-scrollspy text-center"> + <a class="p-1 rounded" href="#simple-list-item-1">Item 1</a> + <a class="p-1 rounded" href="#simple-list-item-2">Item 2</a> + <a class="p-1 rounded" href="#simple-list-item-3">Item 3</a> + <a class="p-1 rounded" href="#simple-list-item-4">Item 4</a> + <a class="p-1 rounded" href="#simple-list-item-5">Item 5</a> + </div> + </div> + <div class="col-8"> + <div data-bs-spy="scroll" data-bs-target="#simple-list-example" data-bs-offset="0" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0"> + <h4 id="simple-list-item-1">Item 1</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="simple-list-item-2">Item 2</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="simple-list-item-3">Item 3</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="simple-list-item-4">Item 4</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + <h4 id="simple-list-item-5">Item 5</h4> + <p>This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.</p> + </div> + </div> + </div> +</div> + +```html +<div class="row"> + <div class="col-4"> + <div id="simple-list-example" class="d-flex flex-column gap-2 simple-list-example-scrollspy text-center"> + <a class="p-1 rounded" href="#simple-list-item-1">Item 1</a> + <a class="p-1 rounded" href="#simple-list-item-2">Item 2</a> + <a class="p-1 rounded" href="#simple-list-item-3">Item 3</a> + <a class="p-1 rounded" href="#simple-list-item-4">Item 4</a> + <a class="p-1 rounded" href="#simple-list-item-5">Item 5</a> + </div> + </div> + <div class="col-8"> + <div data-bs-spy="scroll" data-bs-target="#simple-list-example" data-bs-offset="0" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0"> + <h4 id="simple-list-item-1">Item 1</h4> + <p>...</p> + <h4 id="simple-list-item-2">Item 2</h4> + <p>...</p> + <h4 id="simple-list-item-3">Item 3</h4> + <p>...</p> + <h4 id="simple-list-item-4">Item 4</h4> + <p>...</p> + <h4 id="simple-list-item-5">Item 5</h4> + <p>...</p> + </div> + </div> +</div> +``` + +## Non-visible elements + +Target elements that aren’t visible will be ignored and their corresponding nav items won't receive an `.active` class. Scrollspy instances initialized in a non-visible wrapper will ignore all target elements. Use the `refresh` method to check for observable elements once the wrapper becomes visible. + +```js +document.querySelectorAll('#nav-tab>[data-bs-toggle="tab"]').forEach(el => { + el.addEventListener('shown.bs.tab', () => { + const target = el.getAttribute('data-bs-target') + const scrollElem = document.querySelector(`${target} [data-bs-spy="scroll"]`) + bootstrap.ScrollSpy.getOrCreateInstance(scrollElem).refresh() + }) +}) +``` + +## Usage + +### Via data attributes + +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 `<body>`). Then add the `data-bs-target` attribute with the `id` or class name of the parent element of any Bootstrap `.nav` component. + +```html +<body data-bs-spy="scroll" data-bs-target="#navbar-example"> + ... + <div id="navbar-example"> + <ul class="nav nav-tabs" role="tablist"> + ... + </ul> + </div> + ... +</body> +``` + +### Via JavaScript + +```js +const scrollSpy = new bootstrap.ScrollSpy(document.body, { + target: '#navbar-example' +}) +``` + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< bs-table "table" >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `rootMargin` | string | `0px 0px -25%` | Intersection Observer [rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin) valid units, when calculating scroll position. | +| `smoothScroll` | boolean | `false` | Enables smooth scrolling when a user clicks on a link that refers to ScrollSpy observables. | +| `target` | string, DOM element | `null` | Specifies element to apply Scrollspy plugin. | +| `threshold` | array | `[0.1, 0.5, 1]` | `IntersectionObserver` [threshold](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#threshold) valid input, when calculating scroll position. | + +{{< /bs-table >}} + +{{< callout warning >}} +**Deprecated Options** + +Up until v5.1.3 we were using `offset` & `method` options, which are now deprecated and replaced by `rootMargin`. +To keep backwards compatibility, we will continue to parse a given `offset` to `rootMargin`, but this feature will be removed in **v6**. +{{< /callout >}} + +### Methods + +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `dispose` | Destroys an element's scrollspy. (Removes stored data on the DOM element) | +| `getInstance` | *Static* method to get the scrollspy instance associated with a DOM element. | +| `getOrCreateInstance` | *Static* method to get the scrollspy instance associated with a DOM element, or to create a new one in case it wasn't initialized. | +| `refresh` | When adding or removing elements in the DOM, you'll need to call the refresh method. | +{{< /bs-table >}} + +Here's an example using the refresh method: + +```js +const dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]') +dataSpyList.forEach(dataSpyEl => { + bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh() +}) +``` + +### Events + +{{< bs-table "table" >}} +| Event | Description | +| --- | --- | +| `activate.bs.scrollspy` | This event fires on the scroll element whenever an anchor is activated by the scrollspy. | +{{< /bs-table >}} + +```js +const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]') +firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => { + // do something... +}) +``` diff --git a/site/content/docs/5.2/components/spinners.md b/site/content/docs/5.2/components/spinners.md new file mode 100644 index 0000000..bc1b1e6 --- /dev/null +++ b/site/content/docs/5.2/components/spinners.md @@ -0,0 +1,213 @@ +--- +layout: docs +title: Spinners +description: Indicate the loading state of a component or page with Bootstrap spinners, built entirely with HTML, CSS, and no JavaScript. +group: components +toc: true +--- + +## About + +Bootstrap "spinners" can be used to show the loading state in your projects. They're built only with HTML and CSS, meaning you don't need any JavaScript to create them. You will, however, need some custom JavaScript to toggle their visibility. Their appearance, alignment, and sizing can be easily customized with our amazing utility classes. + +For accessibility purposes, each loader here includes `role="status"` and a nested `<span class="visually-hidden">Loading...</span>`. + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +## Border spinner + +Use the border spinners for a lightweight loading indicator. + +{{< example >}} +<div class="spinner-border" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +{{< /example >}} + +### Colors + +The border spinner uses `currentColor` for its `border-color`, meaning you can customize the color with [text color utilities][color]. You can use any of our text color utilities on the standard spinner. + +{{< example >}} +{{< spinner.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<div class="spinner-border text-{{ .name }}" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +{{- end -}} +{{< /spinner.inline >}} +{{< /example >}} + +{{< callout info >}} +**Why not use `border-color` utilities?** Each border spinner specifies a `transparent` border for at least one side, so `.border-{color}` utilities would override that. +{{< /callout >}} + +## Growing spinner + +If you don't fancy a border spinner, switch to the grow spinner. While it doesn't technically spin, it does repeatedly grow! + +{{< example >}} +<div class="spinner-grow" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +{{< /example >}} + +Once again, this spinner is built with `currentColor`, so you can easily change its appearance with [text color utilities][color]. Here it is in blue, along with the supported variants. + +{{< example >}} +{{< spinner.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<div class="spinner-grow text-{{ .name }}" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +{{- end -}} +{{< /spinner.inline >}} +{{< /example >}} + +## Alignment + +Spinners in Bootstrap are built with `rem`s, `currentColor`, and `display: inline-flex`. This means they can easily be resized, recolored, and quickly aligned. + +### Margin + +Use [margin utilities][margin] like `.m-5` for easy spacing. + +{{< example >}} +<div class="spinner-border m-5" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +{{< /example >}} + +### Placement + +Use [flexbox utilities][flex], [float utilities][float], or [text alignment][text] utilities to place spinners exactly where you need them in any situation. + +#### Flex + +{{< example >}} +<div class="d-flex justify-content-center"> + <div class="spinner-border" role="status"> + <span class="visually-hidden">Loading...</span> + </div> +</div> +{{< /example >}} + +{{< example >}} +<div class="d-flex align-items-center"> + <strong>Loading...</strong> + <div class="spinner-border ms-auto" role="status" aria-hidden="true"></div> +</div> +{{< /example >}} + +#### Floats + +{{< example >}} +<div class="clearfix"> + <div class="spinner-border float-end" role="status"> + <span class="visually-hidden">Loading...</span> + </div> +</div> +{{< /example >}} + +#### Text align + +{{< example >}} +<div class="text-center"> + <div class="spinner-border" role="status"> + <span class="visually-hidden">Loading...</span> + </div> +</div> +{{< /example >}} + +## Size + +Add `.spinner-border-sm` and `.spinner-grow-sm` to make a smaller spinner that can quickly be used within other components. + +{{< example >}} +<div class="spinner-border spinner-border-sm" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +<div class="spinner-grow spinner-grow-sm" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +{{< /example >}} + +Or, use custom CSS or inline styles to change the dimensions as needed. + +{{< example >}} +<div class="spinner-border" style="width: 3rem; height: 3rem;" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +<div class="spinner-grow" style="width: 3rem; height: 3rem;" role="status"> + <span class="visually-hidden">Loading...</span> +</div> +{{< /example >}} + +## Buttons + +Use spinners within buttons to indicate an action is currently processing or taking place. You may also swap the text out of the spinner element and utilize button text as needed. + +{{< example >}} +<button class="btn btn-primary" type="button" disabled> + <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span> + <span class="visually-hidden">Loading...</span> +</button> +<button class="btn btn-primary" type="button" disabled> + <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span> + Loading... +</button> +{{< /example >}} + +{{< example >}} +<button class="btn btn-primary" type="button" disabled> + <span class="spinner-grow spinner-grow-sm" role="status" aria-hidden="true"></span> + <span class="visually-hidden">Loading...</span> +</button> +<button class="btn btn-primary" type="button" disabled> + <span class="spinner-grow spinner-grow-sm" role="status" aria-hidden="true"></span> + Loading... +</button> +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, spinners now use local CSS variables on `.spinner-border` and `.spinner-grow` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +Border spinner variables: + +{{< scss-docs name="spinner-border-css-vars" file="scss/_spinners.scss" >}} + +Growing spinner variables: + +{{< scss-docs name="spinner-grow-css-vars" file="scss/_spinners.scss" >}} + +For both spinners, small spinner modifier classes are used to update the values of these CSS variables as needed. For example, the `.spinner-border-sm` class does the following: + +{{< scss-docs name="spinner-border-sm-css-vars" file="scss/_spinners.scss" >}} + +### Sass variables + +{{< scss-docs name="spinner-variables" file="scss/_variables.scss" >}} + +### Keyframes + +Used for creating the CSS animations for our spinners. Included in `scss/_spinners.scss`. + +{{< scss-docs name="spinner-border-keyframes" file="scss/_spinners.scss" >}} + +{{< scss-docs name="spinner-grow-keyframes" file="scss/_spinners.scss" >}} + + +[color]: {{< docsref "/utilities/colors" >}} +[display]: {{< docsref "/utilities/display" >}} +[flex]: {{< docsref "/utilities/flex" >}} +[float]: {{< docsref "/utilities/float" >}} +[margin]: {{< docsref "/utilities/spacing" >}} +[sizing]: {{< docsref "/utilities/sizing" >}} +[text]: {{< docsref "/utilities/text" >}} diff --git a/site/content/docs/5.2/components/toasts.md b/site/content/docs/5.2/components/toasts.md new file mode 100644 index 0000000..abcb392 --- /dev/null +++ b/site/content/docs/5.2/components/toasts.md @@ -0,0 +1,401 @@ +--- +layout: docs +title: Toasts +description: Push notifications to your visitors with a toast, a lightweight and easily customizable alert message. +group: components +toc: true +--- + +Toasts are lightweight notifications designed to mimic the push notifications that have been popularized by mobile and desktop operating systems. They're built with flexbox, so they're easy to align and position. + +## Overview + +Things to know when using the toast plugin: + +- Toasts are opt-in for performance reasons, so **you must initialize them yourself**. +- Toasts will automatically hide if you do not specify `autohide: false`. + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +## Examples + +### Basic + +To encourage extensible and predictable toasts, we recommend a header and body. Toast headers use `display: flex`, allowing easy alignment of content thanks to our margin and flexbox utilities. + +Toasts are as flexible as you need and have very little required markup. At a minimum, we require a single element to contain your "toasted" content and strongly encourage a dismiss button. + +{{< example class="bg-light" >}} +<div class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small>11 mins ago</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> +</div> +{{< /example >}} + +{{< callout warning >}} +Previously, our scripts dynamically added the `.hide` class to completely hide a toast (with `display:none`, rather than just with `opacity:0`). This is now not necessary anymore. However, for backwards compatibility, our script will continue to toggle the class (even though there is no practical need for it) until the next major version. +{{< /callout >}} + +### Live example + +Click the button below to show a toast (positioned with our utilities in the lower right corner) that has been hidden by default. + +<div class="toast-container position-fixed bottom-0 end-0 p-3"> + <div id="liveToast" class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small>11 mins ago</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> + </div> +</div> + +<div class="bd-example"> + <button type="button" class="btn btn-primary" id="liveToastBtn">Show live toast</button> +</div> + +```html +<button type="button" class="btn btn-primary" id="liveToastBtn">Show live toast</button> + +<div class="toast-container position-fixed bottom-0 end-0 p-3"> + <div id="liveToast" class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + <img src="..." class="rounded me-2" alt="..."> + <strong class="me-auto">Bootstrap</strong> + <small>11 mins ago</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> + </div> +</div> +``` + +We use the following JavaScript to trigger our live toast demo: + +```js +const toastTrigger = document.getElementById('liveToastBtn') +const toastLiveExample = document.getElementById('liveToast') +if (toastTrigger) { + toastTrigger.addEventListener('click', () => { + const toast = new bootstrap.Toast(toastLiveExample) + + toast.show() + }) +} +``` + +### Translucent + +Toasts are slightly translucent to blend in with what's below them. + +{{< example class="bg-dark" >}} +<div class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small class="text-muted">11 mins ago</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> +</div> +{{< /example >}} + +### Stacking + +You can stack toasts by wrapping them in a toast container, which will vertically add some spacing. + +{{< example class="bg-light" >}} +<div class="toast-container position-static"> + <div class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small class="text-muted">just now</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + See? Just like this. + </div> + </div> + + <div class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small class="text-muted">2 seconds ago</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + Heads up, toasts will stack automatically + </div> + </div> +</div> +{{< /example >}} + +### Custom content + +Customize your toasts by removing sub-components, tweaking them with [utilities]({{< docsref "/utilities/api" >}}), or by adding your own markup. Here we've created a simpler toast by removing the default `.toast-header`, adding a custom hide icon from [Bootstrap Icons]({{< param icons >}}), and using some [flexbox utilities]({{< docsref "/utilities/flex" >}}) to adjust the layout. + +{{< example class="bg-light" >}} +<div class="toast align-items-center" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="d-flex"> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> + <button type="button" class="btn-close me-2 m-auto" data-bs-dismiss="toast" aria-label="Close"></button> + </div> +</div> +{{< /example >}} + +Alternatively, you can also add additional controls and components to toasts. + +{{< example class="bg-light" >}} +<div class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-body"> + Hello, world! This is a toast message. + <div class="mt-2 pt-2 border-top"> + <button type="button" class="btn btn-primary btn-sm">Take action</button> + <button type="button" class="btn btn-secondary btn-sm" data-bs-dismiss="toast">Close</button> + </div> + </div> +</div> +{{< /example >}} + +### Color schemes + +Building on the above example, you can create different toast color schemes with our [color]({{< docsref "/utilities/colors" >}}) and [background]({{< docsref "/utilities/background" >}}) utilities. Here we've added `.text-bg-primary` to the `.toast`, and then added `.btn-close-white` to our close button. For a crisp edge, we remove the default border with `.border-0`. + +{{< example class="bg-light" >}} +<div class="toast align-items-center text-bg-primary border-0" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="d-flex"> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> + <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast" aria-label="Close"></button> + </div> +</div> +{{< /example >}} + +## Placement + +Place toasts with custom CSS as you need them. The top right is often used for notifications, as is the top middle. If you're only ever going to show one toast at a time, put the positioning styles right on the `.toast`. + +{{< example stackblitz_add_js="true" >}} +<form> + <div class="mb-3"> + <label for="selectToastPlacement">Toast placement</label> + <select class="form-select mt-2" id="selectToastPlacement"> + <option value="" selected>Select a position...</option> + <option value="top-0 start-0">Top left</option> + <option value="top-0 start-50 translate-middle-x">Top center</option> + <option value="top-0 end-0">Top right</option> + <option value="top-50 start-0 translate-middle-y">Middle left</option> + <option value="top-50 start-50 translate-middle">Middle center</option> + <option value="top-50 end-0 translate-middle-y">Middle right</option> + <option value="bottom-0 start-0">Bottom left</option> + <option value="bottom-0 start-50 translate-middle-x">Bottom center</option> + <option value="bottom-0 end-0">Bottom right</option> + </select> + </div> +</form> +<div aria-live="polite" aria-atomic="true" class="bg-dark position-relative bd-example-toasts"> + <div class="toast-container p-3" id="toastPlacement"> + <div class="toast"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small>11 mins ago</small> + </div> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> + </div> + </div> +</div> +{{< /example >}} + +For systems that generate more notifications, consider using a wrapping element so they can easily stack. + +{{< example class="bg-dark bd-example-toasts p-0" >}} +<div aria-live="polite" aria-atomic="true" class="position-relative"> + <!-- Position it: --> + <!-- - `.toast-container` for spacing between toasts --> + <!-- - `top-0` & `end-0` to position the toasts in the upper right corner --> + <!-- - `.p-3` to prevent the toasts from sticking to the edge of the container --> + <div class="toast-container top-0 end-0 p-3"> + + <!-- Then put toasts within --> + <div class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small class="text-muted">just now</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + See? Just like this. + </div> + </div> + + <div class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small class="text-muted">2 seconds ago</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + Heads up, toasts will stack automatically + </div> + </div> + </div> +</div> +{{< /example >}} + +You can also get fancy with flexbox utilities to align toasts horizontally and/or vertically. + +{{< example class="bg-dark bd-example-toasts d-flex" >}} +<!-- Flexbox container for aligning the toasts --> +<div aria-live="polite" aria-atomic="true" class="d-flex justify-content-center align-items-center w-100"> + + <!-- Then put toasts within --> + <div class="toast" role="alert" aria-live="assertive" aria-atomic="true"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small>11 mins ago</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> + </div> +</div> +{{< /example >}} + +## Accessibility + +Toasts are intended to be small interruptions to your visitors or users, so to help those with screen readers and similar assistive technologies, you should wrap your toasts in an [`aria-live` region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions). Changes to live regions (such as injecting/updating a toast component) are automatically announced by screen readers without needing to move the user's focus or otherwise interrupt the user. Additionally, include `aria-atomic="true"` to ensure that the entire toast is always announced as a single (atomic) unit, rather than just announcing what was changed (which could lead to problems if you only update part of the toast's content, or if displaying the same toast content at a later point in time). If the information needed is important for the process, e.g. for a list of errors in a form, then use the [alert component]({{< docsref "/components/alerts" >}}) instead of toast. + +Note that the live region needs to be present in the markup *before* the toast is generated or updated. If you dynamically generate both at the same time and inject them into the page, they will generally not be announced by assistive technologies. + +You also need to adapt the `role` and `aria-live` level depending on the content. If it's an important message like an error, use `role="alert" aria-live="assertive"`, otherwise use `role="status" aria-live="polite"` attributes. + +As the content you're displaying changes, be sure to update the [`delay` timeout](#options) so that users have enough time to read the toast. + +```html +<div class="toast" role="alert" aria-live="polite" aria-atomic="true" data-bs-delay="10000"> + <div role="alert" aria-live="assertive" aria-atomic="true">...</div> +</div> +``` + +When using `autohide: false`, you must add a close button to allow users to dismiss the toast. + +{{< example class="bg-light" >}} +<div role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-bs-autohide="false"> + <div class="toast-header"> + {{< placeholder width="20" height="20" background="#007aff" class="rounded me-2" text="false" title="false" >}} + <strong class="me-auto">Bootstrap</strong> + <small>11 mins ago</small> + <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button> + </div> + <div class="toast-body"> + Hello, world! This is a toast message. + </div> +</div> +{{< /example >}} + +While technically it's possible to add focusable/actionable controls (such as additional buttons or links) in your toast, you should avoid doing this for autohiding toasts. Even if you give the toast a long [`delay` timeout](#options), keyboard and assistive technology users may find it difficult to reach the toast in time to take action (since toasts don't receive focus when they are displayed). If you absolutely must have further controls, we recommend using a toast with `autohide: false`. + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap's evolving CSS variables approach, toasts now use local CSS variables on `.toast` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="toast-css-vars" file="scss/_toasts.scss" >}} + +### Sass variables + +{{< scss-docs name="toast-variables" file="scss/_variables.scss" >}} + +## Usage + +Initialize toasts via JavaScript: + +```js +const toastElList = document.querySelectorAll('.toast') +const toastList = [...toastElList].map(toastEl => new bootstrap.Toast(toastEl, option)) +``` + +### Triggers + +{{% js-dismiss "toast" %}} + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< bs-table "table" >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `animation` | boolean | `true` | Apply a CSS fade transition to the toast. | +| `autohide` | boolean | `true` | Automatically hide the toast after the delay. | +| `delay` | number | `5000` | Delay in milliseconds before hiding the toast. | +{{< /bs-table >}} + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `dispose` | Hides an element's toast. Your toast will remain on the DOM but won't show anymore. | +| `getInstance` | *Static* method which allows you to get the toast instance associated with a DOM element. <br> For example: `const myToastEl = document.getElementById('myToastEl')` `const myToast = bootstrap.Toast.getInstance(myToastEl)` Returns a Bootstrap toast instance. | +| `getOrCreateInstance` | *Static* method which allows you to get the toast instance associated with a DOM element, or create a new one, in case it wasn't initialized. <br>`const myToastEl = document.getElementById('myToastEl')` `const myToast = bootstrap.Toast.getOrCreateInstance(myToastEl)` Returns a Bootstrap toast instance. | +| `hide` | Hides an element's toast. **Returns to the caller before the toast has actually been hidden** (i.e. before the `hidden.bs.toast` event occurs). You have to manually call this method if you made `autohide` to `false`. | +| `isShown` | Returns a boolean according to toast's visibility state. | +| `show` | Reveals an element's toast. **Returns to the caller before the toast has actually been shown** (i.e. before the `shown.bs.toast` event occurs). You have to manually call this method, instead your toast won't show. | +{{< /bs-table >}} + +### Events + +{{< bs-table "table" >}} +| Event | Description | +| --- | --- | +| `hide.bs.toast` | This event is fired immediately when the `hide` instance method has been called. | +| `hidden.bs.toast` | This event is fired when the toast has finished being hidden from the user. | +| `show.bs.toast` | This event fires immediately when the `show` instance method is called. | +| `shown.bs.toast` | This event is fired when the toast has been made visible to the user. | +{{< /bs-table >}} + +```js +const myToastEl = document.getElementById('myToast') +myToastEl.addEventListener('hidden.bs.toast', () => { + // do something... +}) +``` diff --git a/site/content/docs/5.2/components/tooltips.md b/site/content/docs/5.2/components/tooltips.md new file mode 100644 index 0000000..a106d9d --- /dev/null +++ b/site/content/docs/5.2/components/tooltips.md @@ -0,0 +1,301 @@ +--- +layout: docs +title: Tooltips +description: Documentation and examples for adding custom Bootstrap tooltips with CSS and JavaScript using CSS3 for animations and data-bs-attributes for local title storage. +group: components +toc: true +--- + +## Overview + +Things to know when using the tooltip plugin: + +- Tooltips rely on the third party library [Popper](https://popper.js.org/) for positioning. You must include [popper.min.js]({{< param "cdn.popper" >}}) before `bootstrap.js`, or use one `bootstrap.bundle.min.js` which contains Popper. +- Tooltips are opt-in for performance reasons, so **you must initialize them yourself**. +- Tooltips with zero-length titles are never displayed. +- Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc). +- Triggering tooltips on hidden elements will not work. +- Tooltips for `.disabled` or `disabled` elements must be triggered on a wrapper element. +- When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior. +- Tooltips must be hidden before their corresponding elements have been removed from the DOM. +- Tooltips can be triggered thanks to an element inside a shadow DOM. + +Got all that? Great, let's see how they work with some examples. + +{{< callout info >}} +{{< partial "callout-info-sanitizer.md" >}} +{{< /callout >}} + +{{< callout info >}} +{{< partial "callout-info-prefersreducedmotion.md" >}} +{{< /callout >}} + +## Examples + +### Enable tooltips + +As mentioned above, you must initialize tooltips before they can be used. One way to initialize all tooltips on a page would be to select them by their `data-bs-toggle` attribute, like so: + +```js +const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]') +const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl)) +``` + +### Tooltips on links + +Hover over the links below to see tooltips: + +{{< example class="tooltip-demo" stackblitz_add_js="true" >}} +<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project. +</p> +{{< /example >}} + +{{< callout warning >}} +{{< partial "callout-warning-data-bs-title-vs-title.md" >}} +{{< /callout >}} + +### Custom tooltips + +{{< added-in "5.2.0" >}} + +You can customize the appearance of tooltips using [CSS variables](#variables). We set a custom class with `data-bs-custom-class="custom-tooltip"` to scope our custom appearance and use it to override a local CSS variable. + +{{< scss-docs name="custom-tooltip" file="site/assets/scss/_component-examples.scss" >}} + + +{{< example class="tooltip-demo" stackblitz_add_js="true" >}} +<button type="button" class="btn btn-secondary" + data-bs-toggle="tooltip" data-bs-placement="top" + data-bs-custom-class="custom-tooltip" + data-bs-title="This top tooltip is themed via CSS variables."> + Custom tooltip +</button> +{{< /example >}} + +### Directions + +Hover over the buttons below to see the four tooltips directions: top, right, bottom, and left. Directions are mirrored when using Bootstrap in RTL. + +<div class="bd-example tooltip-demo"> + <div class="bd-example-tooltips"> + <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" data-bs-title="Tooltip on top">Tooltip on top</button> + <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="Tooltip on right">Tooltip on right</button> + <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="Tooltip on bottom">Tooltip on bottom</button> + <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="Tooltip on left">Tooltip on left</button> + <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" data-bs-title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">Tooltip with HTML</button> + </div> +</div> + +```html +<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" data-bs-title="Tooltip on top"> + Tooltip on top +</button> +<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="Tooltip on right"> + Tooltip on right +</button> +<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="Tooltip on bottom"> + Tooltip on bottom +</button> +<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="Tooltip on left"> + Tooltip on left +</button> +``` + +And with custom HTML added: + +```html +<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" data-bs-title="<em>Tooltip</em> <u>with</u> <b>HTML</b>"> + Tooltip with HTML +</button> +``` + +With an SVG: + +<div class="bd-example tooltip-demo"> + <a href="#" class="d-inline-block" data-bs-toggle="tooltip" data-bs-title="Default tooltip"> + <svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 100 100"> + <rect width="100%" height="100%" fill="#563d7c"/> + <circle cx="50" cy="50" r="30" fill="#007bff"/> + </svg> + </a> +</div> + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +As part of Bootstrap’s evolving CSS variables approach, tooltips now use local CSS variables on `.tooltip` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too. + +{{< scss-docs name="tooltip-css-vars" file="scss/_tooltip.scss" >}} + +### Sass variables + +{{< scss-docs name="tooltip-variables" file="scss/_variables.scss" >}} + +## Usage + +The tooltip plugin generates content and markup on demand, and by default places tooltips after their trigger element. + +Trigger the tooltip via JavaScript: + +```js +const exampleEl = document.getElementById('example') +const tooltip = new bootstrap.Tooltip(exampleEl, options) +``` + +{{< callout warning >}} +##### Overflow `auto` and `scroll` + +Tooltip position attempts to automatically change when a **parent container** has `overflow: auto` or `overflow: scroll` like our `.table-responsive`, but still keeps the original placement's positioning. To resolve this, set the [`boundary` option](https://popper.js.org/docs/v2/modifiers/flip/#boundary) (for the flip modifier using the `popperConfig` option) to any HTMLElement to override the default value, `'clippingParents'`, such as `document.body`: + +```js +const tooltip = new bootstrap.Tooltip('#example', { + boundary: document.body // or document.querySelector('#boundary') +}) +``` +{{< /callout >}} + +### 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). + +{{< callout warning >}} +##### Making tooltips work for keyboard and assistive technology users + +You should only add tooltips to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). Although arbitrary HTML elements (such as `<span>`s) can be made focusable by adding the `tabindex="0"` attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users, and most assistive technologies currently do not announce the tooltip in this situation. Additionally, do not rely solely on `hover` as the trigger for your tooltip, as this will make your tooltips impossible to trigger for keyboard users. +{{< /callout >}} + +```html +<!-- HTML to write --> +<a href="#" data-bs-toggle="tooltip" data-bs-title="Some tooltip text!">Hover over me</a> + +<!-- Generated markup by the plugin --> +<div class="tooltip bs-tooltip-top" role="tooltip"> + <div class="tooltip-arrow"></div> + <div class="tooltip-inner"> + Some tooltip text! + </div> +</div> +``` + +### Disabled elements + +Elements with the `disabled` attribute aren't interactive, meaning users cannot focus, hover, or click them to trigger a tooltip (or popover). As a workaround, you'll want to trigger the tooltip from a wrapper `<div>` or `<span>`, ideally made keyboard-focusable using `tabindex="0"`. + +<div class="tooltip-demo"> +{{< example >}} +<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disabled tooltip"> + <button class="btn btn-primary" type="button" disabled>Disabled button</button> +</span> +{{< /example >}} +</div> + +### Options + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +{{< callout warning >}} +Note that for security reasons the `sanitize`, `sanitizeFn`, and `allowList` options cannot be supplied using data attributes. +{{< /callout >}} + + +{{< bs-table "table" >}} +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `allowList` | object | [Default value]({{< docsref "/getting-started/javascript#sanitizer" >}}) | Object which contains allowed attributes and tags. | +| `animation` | boolean | `true` | Apply a CSS fade transition to the tooltip. | +| `boundary` | string, element | `'clippingParents'` | Overflow constraint boundary of the tooltip (applies only to Popper's preventOverflow modifier). By default, it's `'clippingParents'` and can accept an HTMLElement reference (via JavaScript only). For more information refer to Popper's [detectOverflow docs](https://popper.js.org/docs/v2/utils/detect-overflow/#boundary). | +| `container` | string, element, false | `false` | Appends the tooltip to a specific element. Example: `container: 'body'`. This option is particularly useful in that it allows you to position the tooltip in the flow of the document near the triggering element - which will prevent the tooltip from floating away from the triggering element during a window resize. | +| `customClass` | string, function | `''` | Add classes to the tooltip when it is shown. Note that these classes will be added in addition to any classes specified in the template. To add multiple classes, separate them with spaces: `'class-1 class-2'`. You can also pass a function that should return a single string containing additional class names. | +| `delay` | number, object | `0` | Delay showing and hiding the tooltip (ms)—doesn't apply to manual trigger type. If a number is supplied, delay is applied to both hide/show. Object structure is: `delay: { "show": 500, "hide": 100 }`. | +| `fallbackPlacements` | array | `['top', 'right', 'bottom', 'left']` | Define fallback placements by providing a list of placements in array (in order of preference). For more information refer to Popper's [behavior docs](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements). | +| `html` | boolean | `false` | Allow HTML in the tooltip. If true, HTML tags in the tooltip's `title` will be rendered in the tooltip. If false, `innerText` property will be used to insert content into the DOM. Use text if you're worried about XSS attacks. | +| `offset` | array, string, function | `[0, 0]` | Offset of the tooltip relative to its target. You can pass a string in data attributes with comma separated values like: `data-bs-offset="10,20"`. When a function is used to determine the offset, it is called with an object containing the popper placement, the reference, and popper rects as its first argument. The triggering element DOM node is passed as the second argument. The function must return an array with two numbers: [skidding](https://popper.js.org/docs/v2/modifiers/offset/#skidding-1), [distance](https://popper.js.org/docs/v2/modifiers/offset/#distance-1). For more information refer to Popper's [offset docs](https://popper.js.org/docs/v2/modifiers/offset/#options). | +| `placement` | string, function | `'top'` | How to position the tooltip: auto, top, bottom, left, right. When `auto` is specified, it will dynamically reorient the tooltip. When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The `this` context is set to the tooltip instance. | +| `popperConfig` | null, object, function | `null` | To change Bootstrap's default Popper config, see [Popper's configuration](https://popper.js.org/docs/v2/constructors/#options). When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper. | +| `sanitize` | boolean | `true` | Enable or disable the sanitization. If activated `'template'`, `'content'` and `'title'` options will be sanitized. | +| `sanitizeFn` | null, function | `null` | Here you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization. | +| `selector` | string, false | `false` | If a selector is provided, tooltip objects will be delegated to the specified targets. In practice, this is used to also apply tooltips to dynamically added DOM elements (`jQuery.on` support). See [this issue]({{< param repo >}}/issues/4215) and [an informative example](https://codepen.io/Johann-S/pen/djJYPb). **Note**: `title` attribute must not be used as a selector. | +| `template` | string | `'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'` | Base HTML to use when creating the tooltip. The tooltip's `title` will be injected into the `.tooltip-inner`. `.tooltip-arrow` will become the tooltip's arrow. The outermost wrapper element should have the `.tooltip` class and `role="tooltip"`. | +| `title` | string, element, function | `''` | Default title value if `title` attribute isn't present. If a function is given, it will be called with its `this` reference set to the element that the popover is attached to. | +| `trigger` | string | `'hover focus'` | How tooltip is triggered: click, hover, focus, manual. You may pass multiple triggers; separate them with a space. `'manual'` indicates that the tooltip will be triggered programmatically via the `.tooltip('show')`, `.tooltip('hide')` and `.tooltip('toggle')` methods; this value cannot be combined with any other trigger. `'hover'` on its own will result in tooltips that cannot be triggered via the keyboard, and should only be used if alternative methods for conveying the same information for keyboard users is present. | +{{< /bs-table >}} + +{{< callout info >}} +#### Data attributes for individual tooltips + +Options for individual tooltips can alternatively be specified through the use of data attributes, as explained above. +{{< /callout >}} + +#### Using function with `popperConfig` + +```js +const tooltip = new bootstrap.Tooltip(element, { + popperConfig(defaultBsPopperConfig) { + // const newPopperConfig = {...} + // use defaultBsPopperConfig if needed... + // return newPopperConfig + } +}) +``` + +### Methods + +{{< callout danger >}} +{{< partial "callout-danger-async-methods.md" >}} +{{< /callout >}} + +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `disable` | Removes the ability for an element's tooltip to be shown. The tooltip will only be able to be shown if it is re-enabled. | +| `dispose` | Hides and destroys an element's tooltip (Removes stored data on the DOM element). Tooltips that use delegation (which are created using [the `selector` option](#options)) cannot be individually destroyed on descendant trigger elements. | +| `enable` | Gives an element's tooltip the ability to be shown. **Tooltips are enabled by default.** | +| `getInstance` | *Static* method which allows you to get the tooltip instance associated with a DOM element, or create a new one in case it wasn't initialized. | +| `getOrCreateInstance` | *Static* method which allows you to get the tooltip instance associated with a DOM element, or create a new one in case it wasn't initialized. | +| `hide` | Hides an element's tooltip. **Returns to the caller before the tooltip has actually been hidden** (i.e. before the `hidden.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip. | +| `setContent` | Gives a way to change the tooltip's content after its initialization. | +| `show` | Reveals an element's tooltip. **Returns to the caller before the tooltip has actually been shown** (i.e. before the `shown.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip. Tooltips with zero-length titles are never displayed. | +| `toggle` | Toggles an element's tooltip. **Returns to the caller before the tooltip has actually been shown or hidden** (i.e. before the `shown.bs.tooltip` or `hidden.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip. | +| `toggleEnabled` | Toggles the ability for an element's tooltip to be shown or hidden. | +| `update` | Updates the position of an element's tooltip. | +{{< /bs-table >}} + +```js +const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance + +// setContent example +tooltip.setContent({ '.tooltip-inner': 'another title' }) + +``` + +{{< callout info >}} +The `setContent` method accepts an `object` argument, where each property-key is a valid `string` selector within the popover template, and each related property-value can be `string` | `element` | `function` | `null` +{{< /callout >}} + +### Events + +{{< bs-table >}} +| Event | Description | +| --- | --- | +| `hide.bs.tooltip` | This event is fired immediately when the `hide` instance method has been called. | +| `hidden.bs.tooltip` | This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete). | +| `inserted.bs.tooltip` | This event is fired after the `show.bs.tooltip` event when the tooltip template has been added to the DOM. | +| `show.bs.tooltip` | This event fires immediately when the `show` instance method is called. | +| `shown.bs.tooltip` | This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete). | +{{< /bs-table >}} + +```js +const myTooltipEl = document.getElementById('myTooltip') +const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl) + +myTooltipEl.addEventListener('hidden.bs.tooltip', () => { + // do something... +}) + +tooltip.hide() +``` |