Choose a version:

Modal

Modals are a special type of overlay that shift focus towards a specific action/set of information before the main flow can proceed. They must be specified inside the overlay prop of an activator component (Button, Link or Pressable).

The library automatically applies the WAI-ARIA Dialog pattern to both the activator and the modal content.

Anchor to modalpropsModalProps

Anchor to accessibilityLabel accessibilityLabel string: A label to describe the purpose of the modal that is announced by screen readers. If not set, it will use the value of title.
Anchor to id id string: A unique identifier for the Modal. When no id is set, a globally unique value will be used instead.
Anchor to onClose onClose () => void: Callback when the modal is closed. That is when either the close button, the backdrop, or the escape key are pressed.
Anchor to onOpen onOpen () => void: Callback when the modal is opened. This is called at the beginning of the transition that opens the modal.
Anchor to padding padding boolean: Adds a default spacing around both header (which holds the title) and content of the modal.
Anchor to primaryAction primaryAction RemoteFragment: The primary action to perform, provided as a Button component. The property allows only one button to be rendered.
Anchor to secondaryActions secondaryActions RemoteFragment: The secondary action to perform, provided as a Button component. The property allows only one button to be rendered.
Anchor to size size 'small' | 'auto' | 'large' | 'max' Default: 'auto': Adjust the size of the Modal.

max: expands the Modal to its maximum size, on both the horizontal and vertical axes.
Anchor to title title string: A title rendered at the top of the modal.

ModalProps

accessibilityLabel
A label to describe the purpose of the modal that is announced by screen readers. If not set, it will use the value of `title`.
```
string
```
id
A unique identifier for the Modal. When no `id` is set, a globally unique value will be used instead.
```
string
```
onClose
Callback when the modal is closed. That is when either the close button, the backdrop, or the `escape` key are pressed.
```
() => void
```
onOpen
Callback when the modal is opened. This is called at the beginning of the transition that opens the modal.
```
() => void
```
padding
Adds a default spacing around both header (which holds the `title`) and content of the modal.
```
boolean
```
primaryAction
The primary action to perform, provided as a `Button` component. The property allows only one button to be rendered.
```
RemoteFragment
```
secondaryActions
The secondary action to perform, provided as a `Button` component. The property allows only one button to be rendered.
```
RemoteFragment
```
size
Adjust the size of the Modal. `max`: expands the Modal to its maximum size, on both the horizontal and vertical axes.
```
'small' | 'auto' | 'large' | 'max'
```
title
A title rendered at the top of the modal.
```
string
```

export interface ModalProps {
  /**
   * A unique identifier for the Modal. When no `id` is set,
   * a globally unique value will be used instead.
   */
  id?: string;
  /**
   * Callback when the modal is closed. That is when either the close button, the backdrop,
   * or the `escape` key are pressed.
   */
  onClose?: () => void;
  /**
   * Callback when the modal is opened. This is called at the beginning of the transition
   * that opens the modal.
   */
  onOpen?: () => void;
  /**
   * A title rendered at the top of the modal.
   */
  title?: string;
  /**
   * A label to describe the purpose of the modal that is announced by screen readers.
   * If not set, it will use the value of `title`.
   */
  accessibilityLabel?: string;
  /**
   * Adds a default spacing around both header (which holds the `title`) and content of the modal.
   */
  padding?: boolean;
  /**
   * Adjust the size of the Modal.
   *
   * `max`: expands the Modal to its maximum size, on both the horizontal and vertical axes.
   *
   * @default 'auto'
   */
  size?: 'small' | 'auto' | 'large' | 'max';
  /**
   * The primary action to perform, provided as a `Button` component.
   * The property allows only one button to be rendered.
   */
  primaryAction?: RemoteFragment;
  /**
   * The secondary action to perform, provided as a `Button` component.
   * The property allows only one button to be rendered.
   */
  secondaryActions?: RemoteFragment;
}

Was this section helpful?

Basic Modal

import {

reactExtension,

useApi,

Button,

Link,

Modal,

TextBlock,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const {ui} = useApi();

return (

<Link

overlay={

<Modal

id="my-modal"

padding

title="Return policy"

We have a 30-day return policy, which

means you have 30 days after receiving

your item to request a return.

</TextBlock>

To be eligible for a return, your item

must be in the same condition that you

received it, unworn or unused, with

tags, and in its original packaging.

You’ll also need the receipt or proof

of purchase.

</TextBlock>

<Button

onPress={() =>

ui.overlay.close('my-modal')

}

</Button>

</Modal>

}

Return policy

</Link>

);

}

examples

Basic Modal

React

import {
  reactExtension,
  useApi,
  Button,
  Link,
  Modal,
  TextBlock,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const {ui} = useApi();

  return (
    <Link
      overlay={
        <Modal
          id="my-modal"
          padding
          title="Return policy"
        >
          <TextBlock>
            We have a 30-day return policy, which
            means you have 30 days after receiving
            your item to request a return.
          </TextBlock>
          <TextBlock>
            To be eligible for a return, your item
            must be in the same condition that you
            received it, unworn or unused, with
            tags, and in its original packaging.
            You’ll also need the receipt or proof
            of purchase.
          </TextBlock>
          <Button
            onPress={() =>
              ui.overlay.close('my-modal')
            }
          >
            Close
          </Button>
        </Modal>
      }
    >
      Return policy
    </Link>
  );
}

JS

import {
  extension,
  Button,
  Link,
  Modal,
  TextBlock,
} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root, {ui}) => {
  const modalFragment = root.createFragment();
  const modal = root.createComponent(
    Modal,
    {id: 'my-modal', title: 'Return policy', padding: true},
    [
      root.createComponent(
        TextBlock,
        undefined,
        'We have a 30-day return policy, which means you have 30 days after receiving your item to request a return.',
      ),
      root.createComponent(
        TextBlock,
        undefined,
        'To be eligible for a return, your item must be in the same condition that you received it, unworn or unused, with tags, and in its original packaging. You’ll also need the receipt or proof of purchase.',
      ),
      root.createComponent(
        Button,
        {
          onPress() {
            ui.overlay.close('my-modal');
          },
        },
        'Close',
      ),
    ],
  );
  modalFragment.appendChild(modal);
  const link = root.createComponent(
    Link,
    {overlay: modalFragment},
    'Return policy',
  );

  root.appendChild(link);
});

Preview

Anchor to best-practicesBest Practices

Use modals if:

The information needed to be shown is not critical in completing the checkout process and information cannot be condensed into one sentence.
The information the buyer is entering requires less than two rows of input fields.
The information the buyer is entering is not reliant on information on the page (which is underneath the modal and not visible to them).

Was this section helpful?

Anchor to relatedRelated

APIUi