Modal

Installation

quarto add mcanouil/quarto-modal

This will install the extension under the _extensions subdirectory.

If you’re using version control, you will want to check in this directory.

Usage

To use modals in your HTML Quarto document, you need to include the modal extension in your YAML header.

filters:
  - modal

Options

You can customise the modals generally by setting options in the extensions.modal section of your YAML header.

extensions:
  modal:
    size: null|sm|lg|xl
    backdrop-static: false|true
    scrollable: false|true
    keyboard: true|false
    centred: false|true
    fade: false|true
    fullscreen: false|true|sm|md|lg|xl|xxl

Modal Structure

Modals are structured using a toggle button and a modal container.

Modal Button

Use to create a button that opens a modal.
Use to create a button that closes a modal.
Named arguments:
- target: the modal’s unique identifier required unless inside=true.
- label: the button text.
- classes: custom CSS classes for the button, e.g., btn btn-primary.
- inside: set to true if the dismiss button is inside the modal to be dismissed.

{{< modal <toggle|dismiss> target=<modal-id> label=<label> classes=<classes> inside=<boolean> >}}

Alternatively, you can use the bs-target and bs-toggle attributes directly.

[Button Text]{bs-target="#<modal-id>" bs-toggle="modal"}
[Button Text](#<modal-id>){bs-toggle="modal"}

Or rely on the extension to automatically expand to the correct HTML syntax:

[Button Text](#<modal-id>)

Modal Container

Important

The identifier needs to start with modal- to be recognised by the extension as a modal container.

:::: {#modal-<id> description="<accessibility-description>" <options>}
## Modal Title

Body content goes here.

---

Footer content goes here.
:::

Basic Modal

This sentence is also a trigger to open the modal.

{{< modal toggle target="modal-basic" label="Open Basic Modal" >}}

[This sentence is also a trigger to open the modal.](#modal-basic)

:::: {#modal-basic}

## Basic Modal

This is a basic modal example.

---

{{< modal dismiss inside=true >}}

:::

Fade Modal

{{< modal toggle target="modal-fade" label="Open Fade Modal" >}}

:::: {#modal-fade fade="true"}

## Fade Modal

This modal uses the fade effect.

---

{{< modal dismiss target="modal-fade" label="Close" >}}

:::

Centred Modal

{{< modal toggle target="modal-centred" label="Open Centred Modal" >}}

:::: {#modal-centred centred="true"}

## Centred Modal

This modal is vertically centred.

---

{{< modal dismiss target="modal-centred" label="Close" >}}

:::

Size Options

Modals have three optional sizes. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports.

Size	Size	Class	Modal max-width
Small	`sm`	`.modal-sm`	`300px`
Default		None	`500px`
Large	`lg`	`.modal-lg`	`800px`
Extra large	`xl`	`.modal-xl`	`1140px`

Small Modal

{{< modal toggle target="modal-small" label="Open Small Modal" >}}

:::: {#modal-small size="sm"}

## Small Modal

This modal uses the small size option.

---

{{< modal dismiss target="modal-small" label="Close" >}}

:::

Large Modal

{{< modal toggle target="modal-large" label="Open Large Modal" >}}

:::: {#modal-large size="lg"}

## Large Modal

This modal uses the large size option.

---

{{< modal dismiss target="modal-large" label="Close" >}}

:::

Extra Large Modal

{{< modal toggle target="modal-xlarge" label="Open Extra Large Modal" >}}

:::: {#modal-xlarge size="xl"}

## Extra Large Modal

This modal uses the extra large size option.

---

{{< modal dismiss target="modal-xlarge" label="Close" >}}

:::

Fullscreen Modal

Modals can be made fullscreen at various breakpoints.

Size	Class	Availability
`false`	None	Default
`true`	`.modal-fullscreen`	Always
`sm`	`.modal-fullscreen-sm-down`	`576px`
`md`	`.modal-fullscreen-md-down`	`768px`
`lg`	`.modal-fullscreen-lg-down`	`992px`
`xl`	`.modal-fullscreen-xl-down`	`1200px`
`xxl`	`.modal-fullscreen-xxl-down`	`1400px`

{{< modal toggle target="modal-fullscreen" label="Open Fullscreen Modal" >}}

:::: {#modal-fullscreen fullscreen="true"}

## Fullscreen Modal

This modal covers the entire screen.

---

{{< modal dismiss target="modal-fullscreen" label="Close" >}}

:::

Static Backdrop Modal

{{< modal toggle target="modal-static" label="Open Static Backdrop Modal" >}}

:::: {#modal-static backdrop-static="true"}

## Static Backdrop Modal

Clicking outside will not dismiss this modal.

---

{{< modal dismiss target="modal-static" label="Close" >}}

:::

Scrollable Modal

{{< modal toggle target="modal-scrollable" label="Open Scrollable Modal" >}}

:::: {#modal-scrollable scrollable="true"}

## Scrollable Modal

This modal allows scrolling for long content.

### Section 1

{{< lipsum 1-1 >}}

### Section 2

{{< lipsum 2-2 >}}

### Section 3

{{< lipsum 3-3 >}}

---

{{< modal dismiss target="modal-scrollable" label="Close" >}}

:::

Modal With Keyboard Disabled

{{< modal toggle target="modal-nokeyboard" label="Open No Keyboard Modal" >}}

:::: {#modal-nokeyboard keyboard="false"}

## No Keyboard Modal

Pressing escape will not close this modal.

---

{{< modal dismiss target="modal-nokeyboard" label="Close" >}}

:::

Modal With Custom Footer

{{< modal toggle target="modal-footer" label="Open Modal With Footer" >}}

:::: {#modal-footer}

## Modal With Footer

This modal has a custom footer.

---

:::: {style="text-align: right;"}
{{< modal dismiss target="modal-footer" label="Cancel" >}}
{{< modal dismiss target="modal-footer" label="OK" >}}
:::

:::