Modal

The Modal component is a classic modal overlay in which you can include any content you like. The content under the overlay is inert, meaning users cannot interact with content outside the active modal window. By default, modal overlays contain their own tab sequence so that users cannot navigate outside the component. The component supports the W3C ARIA APG Dialog (Modal) Pattern as well as the W3C ARIA APG Alert and Message Dialogs Pattern.

Examples

Base

Setting the clipScroll prop removes the body scrollbar. By default, the body retains a non scrollable scrollbar to prevent the background from shifting. However, this will set the body to position="fixed", which may cause some layouts to break.

Show code

HTML

<section class="odocs-spaced">
    <p>
        <o-button
            label="Open modal"
            size="medium"
            variant="primary"
            @click="isImageModalActive = true" />

        <o-button
            label="Open modal (clip scroll)"
            size="medium"
            variant="primary"
            @click="isCardModalActive = true" />
    </p>

    <o-modal v-model:active="isImageModalActive">
        <p style="text-align: center">
            <img
                style="background-color: white"
                alt="Oruga logo"
                src="https://avatars2.githubusercontent.com/u/66300512?s=200&v=4" />
        </p>
    </o-modal>

    <o-modal v-model:active="isCardModalActive" :width="640" clip-scroll>
        <div style="padding: 10px; background-color: white">
            <p>
                Lorem ipsum dolor sit amet, consectetur adipiscing elit.
                Etiam sodales leo nec convallis rutrum. Vivamus pharetra
                molestie arcu at dictum. Nulla faucibus leo eget enim
                egestas, in tempus justo venenatis. Duis dictum suscipit
                erat, a dapibus eros lobortis ac. Praesent tempor rhoncus
                convallis. Nullam in ipsum convallis, rutrum elit eget,
                dictum ipsum. Nunc sagittis aliquet massa. Etiam lacus
                sapien, eleifend non eros quis, finibus ornare nisl. Ut
                laoreet sit amet lacus non dignissim. Sed convallis mattis
                enim, sed interdum risus molestie ut. Praesent vel ex
                hendrerit, cursus lectus a, blandit felis. Nam luctus orci
                nec varius commodo.
            </p>
            <p>
                Sed vulputate metus purus, ut egestas erat congue et. Donec
                tellus orci, malesuada eget dolor sed, pellentesque bibendum
                nunc. In eu egestas diam. Integer sed congue massa. Sed a
                urna quam. Morbi vulputate dolor eleifend ligula lobortis
                venenatis. Aenean pellentesque risus sit amet faucibus
                molestie. Aliquam eu lorem aliquet, aliquam nulla in,
                vestibulum lorem. Donec mollis mi at sollicitudin tristique.
                Nullam id nibh pulvinar, dignissim nisl id, gravida risus.
                Nulla arcu elit, scelerisque in sollicitudin et, laoreet et
                metus. Aenean placerat turpis nec tincidunt tempus.
            </p>
        </div>
    </o-modal>
</section>

JS

import { ref } from "vue";

const isImageModalActive = ref(false);
const isCardModalActive = ref(false);

Alert

An alert modal interrupt the user's workflow to communicate an important messages and acquire an explicit response, for example confirmation prompts and error message confirmations. By setting alert prop the alertdialog aria role enables assistive technologies and browsers to distinguish alert dialogs from other dialogs so they have the option of giving alert dialogs special treatment, such as playing a system alert sound.

Show code

HTML

<section class="odocs-spaced">
    <p>
        <o-button
            label="Ask important question"
            size="medium"
            variant="primary"
            @click="isModalActive = true" />
    </p>

    <o-modal
        v-model:active="isModalActive"
        :cancelable="false"
        alert
        aria-labelledby="dialog_label"
        aria-describedby="dialog_desc">
        <h2 id="dialog_label">Confirmation</h2>

        <p id="dialog_desc" style="text-align: center">
            Are you sure you want to delete the internet?
        </p>

        <div>
            <o-button label="No" @click="isModalActive = false" />
            <o-button label="Yes" @click="isModalActive = false" />
        </div>
    </o-modal>
</section>

JS

import { ref } from "vue";

const isModalActive = ref(false);

Teleport

The teleport prop allows the modal to be "teleported" into any DOM node outside the DOM hierarchy of that component. By default, if only a boolean is passed, the modal will be teleported to the document body. In addition, any other destination can be passed as a value to the teleport prop.

Show code

HTML

<section>
    <o-button
        label="Open teleported modal"
        size="medium"
        variant="primary"
        @click="isActive = true" />

    <o-modal v-model:active="isActive" teleport>
        <div style="padding: 10px; background-color: white">
            <p>
                Lorem ipsum dolor sit amet, consectetur adipiscing elit.
                Etiam sodales leo nec convallis rutrum. Vivamus pharetra
                molestie arcu at dictum. Nulla faucibus leo eget enim
                egestas, in tempus justo venenatis. Duis dictum suscipit
                erat, a dapibus eros lobortis ac. Praesent tempor rhoncus
                convallis. Nullam in ipsum convallis, rutrum elit eget,
                dictum ipsum. Nunc sagittis aliquet massa. Etiam lacus
                sapien, eleifend non eros quis, finibus ornare nisl. Ut
                laoreet sit amet lacus non dignissim. Sed convallis mattis
                enim, sed interdum risus molestie ut. Praesent vel ex
                hendrerit, cursus lectus a, blandit felis. Nam luctus orci
                nec varius commodo.
            </p>
        </div>
    </o-modal>
</section>

JS

import { ref } from "vue";

const isActive = ref(false);

Dynamic Component

Instead of using the default slot, the component prop allows to pass any component that will be programmatically rendered inside the modal. Furthermore, an inline component created with a render function can also be passed. Props and events can be passed to the component with props and events props too.

Show code

HTML

<section class="odocs-spaced">
    <o-button
        label="Open component modal"
        size="medium"
        variant="primary"
        @click="isActive = true" />

    <o-modal
        v-model:active="isActive"
        :component="ModalForm"
        :props="{
            title: 'Ship sprockets?',
            message:
                'Do you really want me to ship the selected sprockets?',
        }" />
</section>

JS

import { ref } from "vue";
import ModalForm from "./_modal-form-async.vue";

const isActive = ref(false);

Programmatically

This component provides a programmatic interface that can be accessed by the useOruga() composable. The composable can be used from outside the Vue instance. For example, it can be used in Pinia or Vue Router with this syntax:

    import { useOruga } from "@oruga-ui/oruga-next";
    const oruga = useOruga(); 
    oruga.modal.open({...});

Show code

HTML

<section class="odocs-spaced">
    <p>
        <o-button
            label="Open modal (HTML)"
            size="medium"
            variant="primary"
            @click.prevent="imageModal()" />

        <o-button
            label="Open modal (Component)"
            size="medium"
            variant="primary"
            @click.prevent="cardModal()" />
    </p>
</section>

JS

import { h } from "vue";
import { useOruga } from "@oruga-ui/oruga-next";
import ModalForm from "./_modal-form.vue";

const oruga = useOruga();

function imageModal(): void {
    // here we use a render function to create an dynamic inline component (https://vuejs.org/guide/extras/render-function)
    const vnode = h("p", { style: { "text-align": "center" } }, [
        h("img", {
            alt: "Oruga logo",
            src: "https://avatars2.githubusercontent.com/u/66300512?s=200&v=4",
        }),
    ]);

    oruga.modal.open({
        component: vnode,
    });
}

function cardModal(): void {
    oruga.modal.open({
        component: ModalForm,
        trapFocus: true,
        cancelable: false,
    });
}

A programmatic instance returns a promise to await for. The promise gets resolved when the modal gets closed.

Show code

HTML

<section class="odocs-spaced">
    <p>
        <o-button
            label="Open prompt"
            size="medium"
            variant="primary"
            @click.prevent="promptModal()" />
        <o-button
            label="Open prompt (closeAll timeout)"
            size="medium"
            variant="primary"
            @click.prevent="promptModalCloseAll()" />
    </p>
</section>

JS

import { useOruga } from "@oruga-ui/oruga-next";
import ModalForm from "./_modal-form-async.vue";

const oruga = useOruga();

const promptModal = async (): Promise<void> => {
    const instance = oruga.modal.open({
        component: ModalForm,
        props: {
            title: "Ship sprockets?",
            message: "Do you really want me to ship the selected sprockets?",
        },
        trapFocus: true,
    });

    // wait until the modal got closed
    const result = await instance.promise;

    oruga.notification.open({
        duration: 5000,
        message: "Modal dialog returned " + JSON.stringify(result),
        variant: "info",
        position: "top",
        closable: true,
    });
};

const promptModalCloseAll = async (): Promise<void> => {
    const instance = oruga.modal.open({
        component: ModalForm,
        props: {
            title: "Close All test",
            message:
                "There is a 3 second timeout that will close all programmatic modals",
        },
        trapFocus: true,
    });

    setTimeout(() => oruga.modal.closeAll({ action: "closeAll" }), 3 * 1000);

    // wait until the modal got closed
    const result = await instance.promise;

    oruga.notification.open({
        duration: 5000,
        message: "Modal dialog returned " + JSON.stringify(result),
        variant: "info",
        position: "top",
        closable: true,
    });
};

Modal component

Classic modal overlay to include any content you may need.

<o-modal></o-modal>

Props

Prop name	Description	Type	Values	Default
active	Whether modal is active or not, use v-model:active to make it two-way binding	boolean	-	false
alert	This enables the alertdialog role, allowing assistive technologies and browsers to distinguish alert modals from other modals. Alert modals interrupt the user's workflow to communicate an important messages and acquire an explicit response.	boolean	-	From config: modal: {   alert: false }
animation	Custom animation (transition name)	string	-	From config: modal: {   animation: "zoom-out" }
ariaCloseLabel	Accessibility label for the close button	string	-	From config: modal: {   ariaCloseLabel: "Close" }
ariaLabel	Accessibility aria-label to be passed to the div wrapper element	string	-	From config: modal: {   ariaLabel: undefined }
autoFocus	Automatically focus modal when active	boolean	-	From config: modal: {   autoFocus: true }
cancelable	Is Modal cancleable by clicking 'X', pressing escape or clicking outside	boolean | string[]	escape, x, outside, button, true, false	From config: modal: {   cancelable: ["escape","x","outside"] }
clipScroll	Set true to remove the body scrollbar. When false, a non-scrollable scrollbar will be kept to avoid moving the background, but will set the body to a fixed position, which may break some layouts.	boolean	-	From config: modal: {   clipScroll: false }
closeIcon	Close icon name	string	-	From config: modal: {   closeIcon: "close" }
closeIconSize	Size of close icon	string	small, medium, large	From config: modal: {   closeIconSize: "medium" }
component	Component to be injected. Close the component by emitting a 'close' event — $emit('close')	Component	-
content	Text content, unnecessary when default slot is used	string	-
events	Events to be binded to the injected component	{}	-
fullScreen	Display modal as full screen	boolean	-	false
mobileBreakpoint	Mobile breakpoint as max-width value	string	-	From config: modal: {   mobileBreakpoint: undefined }
overlay	Show an overlay	boolean	-	From config: modal: {   overlay: true }
override	Override existing theme classes completely	boolean	-
props	Props to be binded to the injected component	any	-
teleport	Append the component to another part of the DOM. Set true to append the component to the body. In addition, any CSS selector string or an actual DOM node can be used.	boolean | object | string	-	From config: modal: {   teleport: false }
trapFocus	Trap focus inside the modal	boolean	-	From config: modal: {   trapFocus: true }
width	Width of the Modal	number | string	-	From config: modal: {   width: 960 }

Events

Event name	Properties	Description
update:active	value boolean - updated active prop	active prop two-way binding
close	value unknown - close event data	on component close event

Slots

Name	Description	Bindings
default	Modal default content, default is content prop	close (...args): void - function to close the component

Class Inspector

Classes applied to the element:

How does the Class props inspector work?

Class props inspector is useful to see class props you want to use to customize Oruga components and how they change a component. You can click on Inspect button to find the exact element where a specific class prop acts.

In the Class props inspector there are other columns:

Class prop

This column contains the name of the Class prop you want to inspect.
If you find a name with a link ( ▷ classPropName) this refers to a subitem (e.g. Dropdown Item in Dropdown).

Description

This column contains the description of the Class prop you want to inspect.
👉 This icon indicates some warning, e.g. this Class prop is visible only on mobile.

Props

This column contains a list of props that activate the class, e.g. if a class prop contains disabled prop it means that only when the component has disabled prop.

Suffixes

This column contains all the possible suffixes that you'll receive if you use a function to customize your Class prop.

Class prop	Description	Props	Suffixes
rootClass	Class of the root element.
mobileClass	Class of the root element when on mobile. 👉 Switch to mobile view to see it in action!
activeClass	Class of the root element when active.	active
overlayClass	Class of the overlay element.
contentClass	Class of the content element.
fullScreenClass	Class of the content element when fullscreen.	fullScreen
closeClass	Class of the close button element.
scrollClipClass	Class of the body when is open and scroll is clipped.	clipScroll
scrollKeepClass	Class of the body when is open and scroll is keeped.	clipScroll

Sass variables

Current theme ➜ Oruga

SASS Variable	Default
$modal-content-background-color	var(--#{$prefix}white)
$modal-content-border-radius	var(--#{$prefix}base-border-radius)
$modal-overlay-background-color	hsla(0, 0%, 4%, 0.86)
$modal-close-border-radius	var( --#{$prefix}base-border-radius-rounded)
$modal-close-right	20px
$modal-close-top	20px
$modal-close-size	32px
$modal-close-color	var(--#{$prefix}white)
$modal-content-fullscreen-background-color	#f5f5f5
$modal-content-max-height	calc(100vh - 160px)
$modal-content-margin	0 auto
$modal-zindex	40

See ➜ 📄 Full scss file

Current theme ➜ Bulma

The theme does not have any custom variables for this component.

Current theme ➜ Bootstrap

The theme does not have any custom variables for this component.