Modals

import { ModalsDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';

export default Layout(MDX_DATA.Modals);

Installation

Setup ModalsProvider

Wrap your app with ModalsProvider component:

import { MantineProvider } from '@mantine/core';
import { ModalsProvider } from '@mantine/modals';

function Demo() {
  return (
    <MantineProvider>
      <ModalsProvider></ModalsProvider>
    </MantineProvider>
  );
}

Confirm modal

The @mantine/modals package includes a special modal that can be used for confirmations. The component includes confirm and cancel buttons and supports children to display additional information about the action. Use the openConfirmModal function to open a confirm modal:

openConfirmModal function accepts one argument with the following properties:

• modalId – modal id, defaults to a random id, can be used to close the modal programmatically
• children – additional modal content displayed before actions
• onCancel – called when the cancel button is clicked
• onConfirm – called when the confirm button is clicked
• closeOnConfirm – should the modal be closed when the confirm button is clicked, defaults to true
• closeOnCancel – should the modal be closed when the cancel button is clicked, defaults to true
• cancelProps – cancel button props
• confirmProps – confirm button props
• groupProps – buttons Group props
• labels – cancel and confirm button labels, can be defined on ModalsProvider

Using these properties, you can customize the confirm modal to match current context requirements:

To set up shared labels for confirm modals, set labels on ModalsProvider:

import { ModalsProvider } from '@mantine/modals';

function Demo() {
  return (
    <ModalsProvider labels={{ confirm: 'Submit', cancel: 'Cancel' }}>
    </ModalsProvider>
  );
}

Context modals

You can define any number of modals in the ModalsProvider context:

import { Button, Text } from '@mantine/core';
import { ContextModalProps, ModalsProvider } from '@mantine/modals';

const TestModal = ({
  context,
  id,
  innerProps,
}: ContextModalProps<{ modalBody: string }>) => (
  <>
    <Text size="sm">{innerProps.modalBody}</Text>
    <Button fullWidth mt="md" onClick={() => context.closeModal(id)}>
      Close modal
    </Button>
  </>
);

function Demo() {
  return (
    <ModalsProvider
      modals={{ demonstration: TestModal /* ...other modals */ }}
    >
    </ModalsProvider>
  );
}

And then open one of these modals with the modals.openContextModal function. The modals.openContextModal function accepts 2 arguments: modal key (should match one defined on ModalsProvider) and modal props:

Typesafe context modals

By default, innerProps and modal are not typesafe. You can add type safety with a TypeScript module declaration.

const TestModal = ({
  context,
  id,
  innerProps,
}: ContextModalProps<{ modalBody: string }>) => (
  <>
    <Text size="sm">{innerProps.modalBody}</Text>
    <Button fullWidth mt="md" onClick={() => context.closeModal(id)}>
      Close modal
    </Button>
  </>
);
const modals = {
  demonstration: TestModal,
  /* ...other modals */
};
declare module '@mantine/modals' {
  export interface MantineModalsOverride {
    modals: typeof modals;
  }
}
function Demo() {
  return (
    <ModalsProvider modals={modals}>
    </ModalsProvider>
  );
}

Type-safe context modals will force you to use the correct types for openContextModal:

import { closeModal, openContextModal } from '@mantine/modals';

openContextModal({
  modal: 'demonstration',
  title: 'Test modal from context',
  innerProps: {
    modalBody:
      'This modal was defined in ModalsProvider, you can open it anywhere in your app with useModals hook',
  },
});
closeModal('demonstration');

Content modals

With the modals.open function, you can open a modal with any content:

Multiple opened modals

You can open multiple layers of modals. Every opened modal is added as the first element in the modals queue. To close all opened modals, call the modals.closeAll() function:

Modal props

You can pass props down to the Modal component by adding them to the argument of every modals.x function. Example of setting the radius, size, and withCloseButton props:

Dynamic content and the modals manager

The modals manager allows you to dynamically update the content and properties of both standard and context modals after they are opened.

To update regular modals, use the modals.updateModal function:

Context modals can also be updated dynamically using modals.updateContextModal: