This Quarto extension provides a simple way to create Bootstrap 5 offcanvas components in your HTML documents.

Offcanvas components are sliding panels that can be triggered from buttons and appear from any edge of the viewport.

quarto add mcanouil/quarto-offcanvas@1.3.0

This will install the extension under the _extensions subdirectory.

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

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

filters:
  - path: offcanvas
    at: pre-quarto

Create an offcanvas component using a fenced div with the .offcanvas class:

:::: {.offcanvas}

# Offcanvas Title

Your content goes here.

:::

Customise the offcanvas behaviour with attributes:

:::: {.offcanvas placement="end" width="450px" trigger-text="Settings"}

# Settings Panel

Configure your preferences here.

:::

For more information about Bootstrap offcanvas components, see the official Bootstrap documentation.

This extension targets Bootstrap 5 and assumes the version that Quarto ships (currently 5.3.x).

• Bootstrap 5.0 or later is required for offcanvas itself.
• Bootstrap 5.2 or later is required for the responsive .offcanvas-{sm,md,lg,xl,xxl} classes used by responsive.
• The breakpoint thresholds (sm, md, lg, xl, xxl) follow Bootstrap's defaults (576, 768, 992, 1200, 1400 px).
• The --bs-offcanvas-transition-duration CSS custom property used by animation was introduced in Bootstrap 5.3; on earlier versions only the fallback transition-duration declaration takes effect.

Bootstrap 4 and earlier do not include an offcanvas component, so the extension produces no output in those documents.

The extension can automatically convert Quarto margin content (elements with .column-margin or .aside classes) into offcanvas components.

This is particularly useful for making margin notes accessible on mobile devices while not cluttering the main content area.

To enable this feature:

---
format: html
extensions:
  offcanvas:
    overtake-margins: true
    placement: end
    width: 450px
    trigger-class: btn btn-sm btn-outline-secondary
---

When enabled, all margin content will be converted to offcanvas panels with trigger buttons placed in the margin.

The trigger button text is automatically extracted from the first 30 characters of the margin content, unless overridden with the trigger-text attribute.

You can customise individual margin elements using attributes:

:::: {.column-margin trigger-text="View details" title="Additional Info"}
Content here.
:::

All standard offcanvas attributes are supported on margin elements (placement, width, height, backdrop, scroll, keyboard, trigger-class, trigger-icon, title, show-close).

Set default values for all offcanvas components in the document metadata:

---
title: "My Document"
format: html
extensions:
  offcanvas:
    placement: end
    width: 450px
    trigger-class: btn btn-outline-secondary
---

:::: {.offcanvas placement="start" trigger-text="Menu" trigger-icon="bi bi-list"}

# Navigation

- [Home](#home)
- [About](#about)
- [Contact](#contact)

:::

:::: {.offcanvas placement="end" width="350px" trigger-text="Settings"}

# Preferences

- [ ] Dark mode
- [ ] Notifications
- [ ] Auto-save

:::

:::: {.offcanvas placement="top" height="200px" backdrop="false" scroll="true"}

# Announcements

Important system notice.

:::

Use a horizontal rule to separate body and footer:

:::: {.offcanvas placement="end" trigger-text="Details"}

# Details

Main content here.

---

**Footer Section**

[Save](#){.btn .btn-primary}
[Cancel](#){.btn .btn-secondary bs-dismiss="offcanvas"}

:::

Set trigger-position="none" to manage the trigger yourself:

:::: {#my-custom-offcanvas .offcanvas trigger-position="none"}

# Custom Offcanvas

This offcanvas has no automatic trigger.

You control when and how to open it.

:::

[Open Custom Offcanvas](#my-custom-offcanvas){bs-toggle="offcanvas"}

This allows you to create custom trigger elements anywhere in your document using the syntax:

[Link Text](#offcanvas-id){bs-toggle="offcanvas"}

Use trigger-type="text" for a plain text trigger instead of a button:

:::: {.offcanvas trigger-type="text" trigger-text="Click here" trigger-class="text-primary"}

# Text Trigger Example

This offcanvas is triggered by plain text instead of a button.

:::

Use trigger-class="none" or trigger-class="" to remove all CSS classes:

:::: {.offcanvas trigger-class="none" trigger-text="Plain Trigger"}

# No Styling

This trigger has no CSS classes applied.

:::

Tune the slide-in/out duration using the animation attribute.

The presets are none (0ms), fast (150ms), normal (300ms), and slow (500ms).

The value is applied via the --bs-offcanvas-transition-duration CSS custom property, so it inherits Bootstrap's easing curve.

:::: {.offcanvas animation="fast" trigger-text="Fast slide"}

# Fast slide

This panel slides in over 150 milliseconds.

:::

Set auto-dismiss to a positive number of milliseconds to close the panel automatically after it has been shown.

The timer is cancelled if the user dismisses the panel earlier (via the close button, backdrop, or Escape).

:::: {.offcanvas auto-dismiss="3000" trigger-text="Notice"}

# Notice

This panel closes itself after 3 seconds.

:::

Nest a child div with class .offcanvas-trigger inside an offcanvas to use arbitrary markdown as the trigger content.

This takes precedence over trigger-text and trigger-icon for that panel.

:::: {.offcanvas trigger-class="btn btn-outline-primary"}

:::{.offcanvas-trigger}
**Open** the panel for *details* `now`.
:::

# Custom trigger

The trigger content above came from a `.offcanvas-trigger` child div.

:::

Use trigger-style to add inline CSS to the trigger element.

For text triggers, your style is merged with the built-in cursor: pointer; hint rather than replacing it.

:::: {.offcanvas trigger-type="text" trigger-text="Styled" trigger-style="color: teal; text-decoration: underline;"}

# Styled text trigger

Pointer cursor is preserved alongside your custom style.

:::

Use "left" and "right" as convenient aliases:

:::: {.offcanvas placement="left"}

# Left Panel

This is equivalent to `placement="start"`.

:::

:::: {.offcanvas placement="right"}

# Right Panel

This is equivalent to `placement="end"`.

:::

Here is the source code for a comprehensive example: example.qmd.

Outputs of example.qmd:

• HTML