From c1d5a801b4bc66e3866f815be00e11d1b20d3539 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 24 Jun 2023 14:44:36 +0200 Subject: Adding upstream version 5.3.0+dfsg. Signed-off-by: Daniel Baumann --- site/content/docs/5.3/components/modal.md | 871 ++++++++++++++++++++++++++++++ 1 file changed, 871 insertions(+) create mode 100644 site/content/docs/5.3/components/modal.md (limited to 'site/content/docs/5.3/components/modal.md') diff --git a/site/content/docs/5.3/components/modal.md b/site/content/docs/5.3/components/modal.md new file mode 100644 index 0000000..ba2a51a --- /dev/null +++ b/site/content/docs/5.3/components/modal.md @@ -0,0 +1,871 @@ +--- +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 `` 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 "callouts/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. + +
+
+
+
+
+
Modal title
+ +
+
+

Modal body text goes here.

+
+
+ + +
+
+
+
+
+ +```html +
+
+
+
+
Modal title
+ +
+
+

Modal body text goes here.

+
+
+ + +
+
+
+
+``` + +{{< callout info >}} +In the above static example, we use `
`, 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 `

`. 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. + + + +
+ +
+ +```html + + + + + +``` + +### 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. + + + +
+ +
+ +```html + + + + + +``` + +### 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. + + + +
+ +
+ +You can also create a scrollable modal that allows scroll the modal body by adding `.modal-dialog-scrollable` to `.modal-dialog`. + + + +
+ +
+ +```html + +
+ ... +
+``` + +### Vertically centered + +Add `.modal-dialog-centered` to `.modal-dialog` to vertically center the modal. + + + + + +
+ + +
+ +```html + +
+ ... +
+ + +
+ ... +
+``` + +### 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. + + + +
+ +
+ +```html +
+

Popover in a modal

+

This triggers a popover on click.

+
+

Tooltips in a modal

+

This link and that link have tooltips on hover.

+
+``` + +### 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. + + + +
+ +
+ +```html +
+
+
+
.col-md-4
+
.col-md-4 .ms-auto
+
+
+
.col-md-3 .ms-auto
+
.col-md-2 .ms-auto
+
+
+
.col-md-6 .ms-auto
+
+
+
+ Level 1: .col-sm-9 +
+
+ Level 2: .col-8 .col-sm-6 +
+
+ Level 2: .col-4 .col-sm-6 +
+
+
+
+
+
+``` + +### 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" >}} + + + + + +{{< /example >}} + +{{< js-docs name="varying-modal-content" file="site/assets/js/snippets.js" >}} + +### 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 >}} + + + +{{< /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 + +``` + +### 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 | None | `500px` | +| Large | `.modal-lg` | `800px` | +| Extra large | `.modal-xl` | `1140px` | +{{< /bs-table >}} + +Our default modal without modifier class constitutes the "medium" size modal. + +
+ + + +
+ +```html +
...
+
...
+
...
+``` + + + + + + + +## 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 >}} + +
+ + + + + + +
+ +```html + +
+ ... +
+``` + + + + + + + + + + + + + +## 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" >}} + +### Sass loops + +[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 + +``` + +#### 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 "callouts/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 `
`). + +{{< 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... +}) +``` -- cgit v1.2.3