Skip to content
Change the site theme
Figma
(information)

Side Modal

Design assets pending
Peer review pending

A Side Modal is a page overlay that displays information that does not block the user from interacting with the rest of the page.


Guidelines

Guidelines page anchor

About Side Modal

About Side Modal page anchor

The Side Modal component is a non-modal dialog that sits on top of the right side of the page. It is meant for situations like a preview of a record while looking at a table.

(warning)

Only use one Side Modal on a page

We currenly only support having one Side Modal open on a page. If you have questions, please post a GitHub Discussion(link takes you to an external page).

Side Modal and non-modal dialogs follow these accessibility guidelines:

  • There must be a focusable element inside the dialog.
  • There should be a close button so screen readers have a specific close action to target.
  • A Side Modal is a focus trap, and focus is placed inside it when it's shown.
  • A Side Modal must be triggered by an explicit user action, e.g. clicking a button.
Side Modal with a footer page anchor

The SideModalFooter component has a justifyContent prop that lets you change how the actions are displayed within the footer. It can be set to flex-start, flex-end, or space-between and the default is flex-end.

The SideModalButton renders a Button component and accepts all of its props, which are listed on the Button page.

Side Modal comes with the option of "hooking" into the internal state by using the state hook originally provided by Reakit(link takes you to an external page).

Rather than the state be internal to the component, you can use the useSideModalState hook and pass the returned state to SideModalContainer as the state prop.

This allows you to use certain returned props from the state hook, including functions like hide and show.

It should be noted that when doing so, the state prop takes precedent over the other properties that affect the state or initial state of the Side Modal. They will be ignored in favour of them being provided as arguments to the useSideModalState hook.

For full details on how to use the state hook, and what props to provide it, follow the Non-Modal Dialog Primitive documentation.

Installation

Installation page anchor
yarn add @twilio-paste/side-modal - or - yarn add @twilio-paste/core
import {
SideModal,
SideModalBody,
SideModalButton,
SideModalContainer,
SideModalHeader,
SideModalHeading,
} from '@twilio-paste/core/side-modal';
const SideModalExample: React.FC = () => {
return (
<SideModalContainer>
<SideModalButton variant="primary">Open dialog</SideModalButton>
<SideModal aria-label="My Dialog">
<SideModalHeader>
<SideModalHeading>Dialog header</SideModalHeading>
</SideModalHeader>
<SideModalBody>Dialog content</SideModalBody>
</SideModal>
</SideModalContainer>
);
};
useSideModalState
useSideModalState page anchor

Pass these as part of an object to the useSideModalState hook.

PropTypeDescriptionDefault
baseId?stringSets the ID that will serve as a base for all the items IDs.
visible?booleanWhether the dialog is visible or not.
animated?numberIf true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called after that number of milliseconds.
useSideModalState returned props
useSideModalState returned props page anchor

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

PropTypeDescriptionDefault
baseId?stringSets the ID that will serve as a base for all the items IDs.
visible?booleanWhether the dialog is visible or not.
modal?booleanSets the modal state.true
animating?booleanWhether it's animating or not.
stopAnimation?() => voidStops animation. It's called automatically if there's a CSS transition
show?() => voidChanges the visible state to true.
hide?() => voidChanges the visible state to false.
animated?numberIf true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called after that number of milliseconds.
PropTypeDescriptionDefault
baseId?stringSets the ID that will serve as a base for all the items IDs.
visible?booleanWhether the dialog is visible or not.
children?React.ReactNodeChild components to render into the SideModalContainer

The SideModalButton renders a Button component and accepts all of its props, which are listed on the Button page.

PropTypeDescriptionDefault
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SIDE_MODAL_BUTTON'
PropTypeDescriptionDefault
aria-labelstringTitle of the dialog for screen readers.
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SIDE_MODAL'
children?React.ReactNodeChild components to render into the SideModal
PropTypeDescriptionDefault
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SIDE_MODAL_HEADER'
children?React.ReactNodeChild components to render into the SideModalHeader
i18nDismissLabel?stringThe dismiss button text label'close'
PropTypeDescriptionDefault
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SIDE_MODAL_HEADING'
children?React.ReactNodeChild components to render into the SideModalHeading
as?'h1', 'h2', 'h3', 'h4', 'h5', 'h6'The element the SideModalHeading will render'h2'
PropTypeDescriptionDefault
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SIDE_MODAL_BODY'
children?React.ReactNodeChild components to render into the SideModalBody
PropTypeDescriptionDefault
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SIDE_MODAL_FOOTER'
children?React.ReactNodeChild components to render into the SideModalFooter
PropTypeDescriptionDefault
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SIDE_MODAL_FOOTER_ACTIONS'
justify?'flex-start', 'flex-end', 'space-between'Sets the justify-content CSS property.'flex-end'
children?React.ReactNodeChild components to render into the SideModalFooterActions

Black lives matter.