Skip to content
StudioCMS
UI
Docs

Modal

A dropdown component that takes care of all the annoying bits for you, with added support for programmatic triggers on top.

Usage

'Read the “', Usage, '” section'

Header Content

Modal Content

Size

'Read the “', Size, '” section'

You can change the modal’s size to one of three presets.

Small Modal

Lorem ipsum dolor sit amet. Est corporis rerum est reprehenderit nesciunt qui quibusdam quam non totam quia. Et porro unde et rerum aliquam nam consectetur dolorum et unde optio At delectus alias.

Medium Content

Lorem ipsum dolor sit amet. Est corporis rerum est reprehenderit nesciunt qui quibusdam quam non totam quia. Et porro unde et rerum aliquam nam consectetur dolorum et unde optio At delectus alias.

Large Content

Lorem ipsum dolor sit amet. Est corporis rerum est reprehenderit nesciunt qui quibusdam quam non totam quia. Et porro unde et rerum aliquam nam consectetur dolorum et unde optio At delectus alias.

Dismissable

'Read the “', Dismissable, '” section'

You can change whether a modal can be dismissed by clicking outside of it via the dismissable prop.

Non-dismissable

Lorem ipsum dolor sit amet. Est corporis rerum est reprehenderit nesciunt qui quibusdam quam non totam quia. Et porro unde et rerum aliquam nam consectetur dolorum et unde optio At delectus alias.

If a modal has buttons (see below), the x button in the top right corner will disappear as well.

Buttons

'Read the “', Buttons, '” section'

Modals support both a “cancel” and a “confirm” button.

Buttons

Lorem ipsum dolor sit amet. Est corporis rerum est reprehenderit nesciunt qui quibusdam quam non totam quia. Et porro unde et rerum aliquam nam consectetur dolorum et unde optio At delectus alias.

If you want to, instead of passing the label as a string to the prop, you can instead pass an object with the label and color keys defined to change the way the buttons look:

ModalButtonsExample.astro
---
import { Modal, Button } from '@studiocms/ui/components';
---


<Modal
  id='modal'
  cancelButton={{ label: 'Cancel', color: 'default' }}
  actionButton={{ label: 'Confirm', color: 'danger' }}
>
  <h2 slot='header'>Buttons</h2>
  <div>
    Lorem ipsum dolor sit amet. Est corporis rerum est reprehenderit
    nesciunt qui quibusdam quam non totam quia. Et porro unde et rerum
    aliquam nam consectetur dolorum et unde optio At delectus alias.
  </div>
</Modal>
<Button color='primary' id='modal-trigger'>
  Buttons
</Button>

Registering Callbacks

'Read the “', Registering Callbacks, '” section'

If you want to implement functionality based on which of the buttons is clicked, you can register a callback on each of them.

Script Tag
import { 
class ModalHelper
ModalHelper } from '@studiocms/ui/components';


const 
const modal: ModalHelper
modal = new 
new ModalHelper(id: string, triggerID?: string): ModalHelper
A helper to manage modals.
@param ― id The ID of the modal.
@param ― triggerID The ID of the element that should trigger the modal.
ModalHelper('modal', 'modal-trigger');


const modal: ModalHelper
modal.
ModalHelper.registerCancelCallback: (func: () => void) => void
Registers a callback for the cancel button.
@param ― func The callback function.
registerCancelCallback(() => {
  // Your logic here
});


const modal: ModalHelper
modal.
ModalHelper.registerConfirmCallback: (func: (data?: FormData | undefined) => void) => void
Registers a callback for the confirm button.
@param ― func The callback function. If the modal is a form, the function will be called with
the form data as the first argument.
registerConfirmCallback(() => {
  // Your logic here
});

Form Support

'Read the “', Form Support, '” section'

You can turn your modals into forms by supplying the isForm prop! This turns the Cancel button into a reset button and the Confirm button into a submission button. This only changes their types, not their text.

By using the registerConfirmCallback function, you can retrieve the FormData after the Confirm button is clicked. Any inputs in the modal will be included.

Script Tag
import { 
class ModalHelper
ModalHelper } from '@studiocms/ui/components';


const 
const modal: ModalHelper
modal = new 
new ModalHelper(id: string, triggerID?: string): ModalHelper
A helper to manage modals.
@param ― id The ID of the modal.
@param ― triggerID The ID of the element that should trigger the modal.
ModalHelper('modal', 'modal-trigger');


const modal: ModalHelper
modal.
ModalHelper.registerConfirmCallback: (func: (data?: FormData | undefined) => void) => void
Registers a callback for the confirm button.
@param ― func The callback function. If the modal is a form, the function will be called with
the form data as the first argument.
registerConfirmCallback((
formData: any
formData) => {
  // Your logic here
});

Binding Triggers

'Read the “', Binding Triggers, '” section'

You can add multiple triggers to your modal by using the bindTrigger function in combination with an element’s ID.

Script Tag
import { 
class ModalHelper
ModalHelper } from '@studiocms/ui/components';


const 
const modal: ModalHelper
modal = new 
new ModalHelper(id: string, triggerID?: string): ModalHelper
A helper to manage modals.
@param ― id The ID of the modal.
@param ― triggerID The ID of the element that should trigger the modal.
ModalHelper('modal', 'modal-trigger');
const modal: ModalHelper
modal.
ModalHelper.bindTrigger: (elementID: string) => void
A function to add another trigger to show the modal with.
@param ― elementID The ID of the element that should trigger the modal when clicked.
bindTrigger('modal-trigger-two');
const modal: ModalHelper
modal.
ModalHelper.bindTrigger: (elementID: string) => void
A function to add another trigger to show the modal with.
@param ― elementID The ID of the element that should trigger the modal when clicked.
bindTrigger('modal-trigger-three');

Controlling Modals Programatically

'Read the “', Controlling Modals Programatically, '” section'

Similar to dropdowns, modals can be shown and hidden programatically:

Script Tag
import { 
class ModalHelper
ModalHelper } from '@studiocms/ui/components';


const 
const modal: ModalHelper
modal = new 
new ModalHelper(id: string, triggerID?: string): ModalHelper
A helper to manage modals.
@param ― id The ID of the modal.
@param ― triggerID The ID of the element that should trigger the modal.
ModalHelper('modal', 'modal-trigger');


const modal: ModalHelper
modal.
ModalHelper.show: () => void
A function to show the modal.
show();
const modal: ModalHelper
modal.
ModalHelper.hide: () => void
A function to hide the modal.
hide();