Learn about the Modal component for use in UI extensions.
Use the Modal component to render a pop-up overlay containing other components. Like the Panel component, you’ll include the Modal component in an overlay prop within a Button, LoadingButton, Link, Tag, or Image component.To see an example of using overlays, check out HubSpot’s Overlay example project. Note that this is a version 2025.1 project, but the overlay implementation would be similar for projects on version 2025.2 or 2026.03.To format the modal, you’ll use the following subcomponents:
ModalBody (required): contains the main content of the modal.
ModalFooter: an optional component to format the footer section of the modal.
import React from "react";import { Button, Modal, ModalBody, Text, hubspot } from "@hubspot/ui-extensions";hubspot.extend(() => <Extension />);const Extension = () => { return ( <> <Button overlay={ <Modal id="default-modal" title="Example modal" width="md"> <ModalBody> <Text>Welcome to my modal. Thanks for stopping by!</Text> <Text>Close the modal by clicking the X in the top right.</Text> </ModalBody> </Modal> } > Open modal </Button> </> );};
By default, HubSpot handles opening the modal when the user clicks the parent Button, LoadingButton, Link, Tag, or Image component. A close button will also be included in the top right of the modal.
In addition, you can add a close mechanism to a modal using a Button, LoadingButton, Link, Tag or Image with an onClick event that triggers the closeOverlay action. To use this action, you’ll need to include the actions argument in hubspot.extend() as seen in the example code below.Learn more about opening and closing overlays.
import { Button, Modal, ModalBody, ModalFooter, Text, hubspot } from "@hubspot/ui-extensions";hubspot.extend(({ actions }) => <OverlayExampleCard actions={actions} />);const OverlayExampleCard = ({ actions }) => { return ( <> <Button overlay={ <Modal id="default-modal" title="Example modal" width="md"> <ModalBody> <Text>Welcome to my modal. Thanks for stopping by!</Text> <Text>Close the modal by clicking the X in the top right, or using the button below</Text> </ModalBody> <ModalFooter> <Button onClick={() => actions.closeOverlay("default-modal")}>Close modal</Button> </ModalFooter> </Modal> } > Open modal </Button> </> );};
Please note:
You can only have one modal open at a time. Opening a modal while another is already open will cause the first one to close.
A Modal can be opened from a Panel, but a Panel cannot be opened from a Modal.
DO: use this type of overlay for short messages and confirmations. If you want a more lightweight way to communicate a message to the user, check out the Alert component.DO: use the danger variant to confirm destructive actions that cannot be undone. The text should clearly communicate what is being deleted, and the confirmation button should be explicit about the action. For example, never use the word “Okay” to confirm the deletion of an item. Instead, use “Delete”.Learn more about overlays, including when to use a Modal or a Panel.
.gif)
