From db46bfc03f3a22752ef6bd91ae577d893872a216 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 24 Jun 2023 14:44:40 +0200 Subject: Merging upstream version 5.3.0+dfsg. Signed-off-by: Daniel Baumann --- site/content/docs/5.2/components/modal.md | 888 ------------------------------ 1 file changed, 888 deletions(-) delete mode 100644 site/content/docs/5.2/components/modal.md (limited to 'site/content/docs/5.2/components/modal.md') diff --git a/site/content/docs/5.2/components/modal.md b/site/content/docs/5.2/components/modal.md deleted file mode 100644 index ed31b73..0000000 --- a/site/content/docs/5.2/components/modal.md +++ /dev/null @@ -1,888 +0,0 @@ ---- -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 "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. - -
-
-
-
-
-
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 button 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 -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 >}} - - -Open first modal -{{< /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" >}} - -### 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 - -``` - -#### 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 `
`). - -{{< 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