Skip to content

docs(modal): minor udpates to modal docs #3060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 9, 2019
Merged

docs(modal): minor udpates to modal docs #3060

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f6b4072
docs(modal): minor udpates to modal docs
tmorehouse Apr 9, 2019
df4ad88
Merge branch 'dev' into tmorehouse/docs-modal
tmorehouse Apr 9, 2019
3921d1c
Update README.md
tmorehouse Apr 9, 2019
a9ea440
Update README.md
tmorehouse Apr 9, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 74 additions & 61 deletions src/components/modal/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ via the `modal-header` slot, and override the footer completely via the `modal-f
present. Also, if you use the `modal-header` slot, the default header `X` close button will not be
present, nor can you use the `modal-title` slot.

## Toggle Modal Visibility
## Toggle modal visibility

There are several methods that you can employ to toggle the visibility of `<b-modal>`.

Expand All @@ -62,10 +62,10 @@ Other elements can easily show modals using the `v-b-modal` directive.
```

This approach will automatically return focus to the trigger element once the modal closes (similar
to default Bootstrap functionality). Other approaches for toggling modal visibility will require
to default Bootstrap functionality). Other approaches for toggling modal visibility may require
additional code to implement this accessibility feature.

See the **Accessibility** section below for details.
See the [Accessibility](#accessibility) section below for details.

### Using `show()`, `hide()`, and `toggle()` component methods

Expand Down Expand Up @@ -109,7 +109,8 @@ methods.
<!-- b-modal-methods.vue -->
```

The `hide()` method accepts an optional argument. See section **Prevent Closing** below for details.
The `hide()` method accepts an optional string `trigger` argument for defining what triggered the
modal to close. See section [Prevent Closing](#prevent-closing) below for details.

### Using `v-model` property

Expand Down Expand Up @@ -140,7 +141,7 @@ show/hide using `v-model`.

When using the `v-model` property, do not use the `visible` property at the same time.

### Emitting Events on \$root
### Emitting events on \$root

You can emit `bv::show::modal`, `bv::hide::modal`, and `bv::toggle::modal` events on `$root` with
the first argument set to the modal's id. An optional second argument can specify the element to
Expand Down Expand Up @@ -176,7 +177,7 @@ export default {
}
```

### Prevent Closing
### Prevent closing

To prevent `<b-modal>` from closing (for example when validation fails). you can call the
`.preventDefault()` method of the event object passed to your `ok` (**OK** button), `cancel`
Expand Down Expand Up @@ -278,7 +279,7 @@ The `ok`, `cancel`, and `hide` event object contains several properties and meth
| Property or Method | Type | Description |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preventDefault()` | Method | When called prevents the modal from closing |
| `trigger` | Property | Will be one of: `ok` (Default **OK** Clicked), `cancel` (Default **Cancel** clicked), `esc` (if the <kbd>ESC</kbd> key was pressed), `backdrop` (if the backdrop was clicked), `headerclose` (if the header X button was clicked), the argument provided to the `hide()` method, or `undefined` otherwise. |
| `trigger` | Property | Will be one of: `ok` (Default **OK** Clicked), `cancel` (Default **Cancel** clicked), `esc` (if the <kbd>ESC</kbd> key was pressed), `backdrop` (if the backdrop was clicked), `headerclose` (if the header X button was clicked), the first argument provided to the `hide()` method, or `null` otherwise. |
| `target` | Property | A reference to the modal element |
| `vueTarget` | property | A reference to the modal's Vue VM instance |
| `modalId` | property | The modal's ID |
Expand All @@ -290,7 +291,50 @@ advanced control (i.e. detecting what button or action triggerd the modal to hid
`'ok'` or `'cancel'` respectively. The argument passed to `hide()` will be placed into the `trigger`
property of the event object.

## Modal sizing
## Modal content

### Using the grid

Utilize the Bootstrap grid system within a modal by nesting `<b-container fluid>` within the
modal-body. Then, use the normal grid system `<b-row>` (or `<b-form-row>`) and `<b-col>` as you
would anywhere else.

### Tooltips and popovers

Tooltips and popovers can be placed within modals as needed. When modals are closed, any tooltips
and popovers within are also automatically dismissed. Tooltips and popovers are automatically
appended to the modal element (to ensure correct z-indexing), although you can override where they
are appended by specifying a container ID (refer to tooltip and popover docs for details).

```html
<div>
<b-button v-b-modal.modalPopover>Show Modal</b-button>

<b-modal id="modalPopover" title="Modal with Popover" ok-only>
<p>
This
<b-button v-b-popover="'Popover inside a modal!'" title="Popover">Button</b-button>
triggers a popover on click.
</p>
<p>
This <a href="#" v-b-tooltip title="Tooltip in a modal!">Link</a> will show a tooltip on
hover.
</p>
</b-modal>
</div>

<!-- b-modal-popover.vue -->
```

## Lazy loading

Modal will always render its HTML markup in the document at the location that the `<b-modal>`
component is placed (even if it is not shown). You can hide the modal markup from being in the DOM
while modal is in the hidden state by setting the `lazy` prop.

## Styling, options, and customization

### Modal sizing

Modals have three optional sizes, available via the prop `size`. These sizes kick in at certain
breakpoints to avoid horizontal scrollbars on narrower viewports. Valid optional sizes are `sm`,
Expand All @@ -312,7 +356,7 @@ breakpoints to avoid horizontal scrollbars on narrower viewports. Valid optional

The `size` prop maps the size to the `.modal-<size>` classes.

## Scrolling long content
### 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.
Expand Down Expand Up @@ -350,7 +394,7 @@ prop `scrollable` to `true`.
<!-- b-modal-scrollable-content.vue -->
```

## Vertically centered modal
### Vertically centered modal

Vertically center your modal in the viewport by setting the `centered` prop.

Expand All @@ -369,40 +413,7 @@ Vertically center your modal in the viewport by setting the `centered` prop.

Feel free to mix vertically `centered` with `scrollable`.

## Using the grid

Utilize the Bootstrap grid system within a modal by nesting `<b-container fluid>` within the
modal-body. Then, use the normal grid system `<b-row>` (or `<b-form-row>`) and `<b-col>` as you
would anywhere else.

## Tooltips and popovers

Tooltips and popovers can be placed within modals as needed. When modals are closed, any tooltips
and popovers within are also automatically dismissed. Tooltips and popovers are automatically
appended to the modal element (to ensure correct z-indexing), although you can override where they
are appended by specifying a container ID (refer to tooltip and popover docs for details).

```html
<div>
<b-button v-b-modal.modalPopover>Show Modal</b-button>

<b-modal id="modalPopover" title="Modal with Popover" ok-only>
<p>
This
<b-button v-b-popover="'Popover inside a modal!'" title="Popover">Button</b-button>
triggers a popover on click.
</p>
<p>
This <a href="#" v-b-tooltip title="Tooltip in a modal!">Link</a> will show a tooltip on
hover.
</p>
</b-modal>
</div>

<!-- b-modal-popover.vue -->
```

## Variants
### Variants

Control the header, footer, and body background and text variants by setting the
`header-bg-variant`, `header-text-variant`, `body-bg-variant`, `body-text-variant`,
Expand Down Expand Up @@ -522,18 +533,12 @@ You can also apply arbitrary classes to the modal dialog container, content (mod
header, body and footer via the `modal-class`, `content-class`, `header-class`, `body-class` and
`footer-class` props, respectively. The props accept either a string or array of strings.

## Lazy loading

Modal will always render its HTML markup in the document at the location that the `<b-modal>`
component is placed (even if it is not shown). You can hide the modal markup from being in the DOM
while modal is in the hidden state by setting the `lazy` prop.

## Disable open and close animation
### Disable open and close animation

To disable the fading transition/animation when modal opens and closes, just set the prop `no-fade`
on the `<b-modal>` component.

## Disabling built-in buttons
### Disabling built-in buttons

You can disable the built-in footer buttons programmatically.

Expand Down Expand Up @@ -597,7 +602,7 @@ export default {
```

Refer to the [Events](/docs/components/modal#component-reference) section of documentation for the
full list of events.
full list of events emitted.

## Accessibility

Expand All @@ -608,7 +613,7 @@ For `aria-labelledby` and `aria-described` by attributes to appear on the modal,
an `id` attribute on `<b-modal>`. `aria-labelledby` will not be present if you have the header
hidden.

## Auto Focus on open
### Auto focus on open

`<b-modal>` will autofocus the modal container when opened.

Expand Down Expand Up @@ -647,13 +652,21 @@ export default {
}
```

## Returning focus to the triggering element
Note: it is not reccommended to autofocus an input inside a modal for accessibility reasons, as
screen reader users will not know the context of where the input is. It is best to let `<b-modal>`
focus the modal container.

### Returning focus to the triggering element

For accessibility reasons, it is desirable to return focus to the element that triggered the opening
of the modal, when the modal closes. `<b-modal>` provides several methods and options for returning
focus to the triggering element.
of the modal, when the modal closes.

`<b-modal>` will try and automatically determine which element had focus before the modal was opened,
and will return the focus to that element when the modal has hidden if possible. However, several
methods and options are provided to allow you to specify the element to return focus to once the
modal has hidden.

### Specify Return Focus Element via the `return-focus` Prop
#### Specify return focus element via the `return-focus` prop

You can also specify an element to return focus to, when modal closes, by setting the `return-focus`
prop to one of the following:
Expand All @@ -669,13 +682,13 @@ This method for returning focus is handy when you use the `<b-modal>` methods `s
or the `v-model` prop. Note this property takes precedence over other methods of specifying the
return focus element.

### Auto Return Focus
#### Auto return focus

When `<b-modal>` is opened via the `v-b-modal` directive on an element, focus will be returned to
this element automatically when `<b-modal>` closes, unless an element has been specified via the
`return-focus` prop.

### Specify Return Focus via Event
#### Specify return focus via event

When using the `bv::show::modal` event (emitted on `$root`), you can specify a second argument which
is the element to return focus to. This argument accepts the same types as the `return-focus` prop.
Expand All @@ -696,7 +709,7 @@ property:
**Note:** If the `<b-modal>` has the `return-focus` prop set, then the element specified via the
event will be ignored.

## Keyboard Navigation
### Keyboard navigation

When tabbing through elements within a `<b-modal>`, if focus attempts to leave the modal into the
document, it will be brought back into the modal.
Expand Down