Modal

yarn add @clayui/modal

A modal is a secondary window that communicates or provides an action inside the same process.

React Component
CSS / Markup

useModal hook
- Usage
Header
Provider
API

You may want to compose your content and customize with your use cases or add your own components while still keeping the logic of a modal.

import ClayButton from '@clayui/button';
import ClayModal, {useModal} from '@clayui/modal';

import ClayButton from '@clayui/button';
import ClayModal, {useModal} from '@clayui/modal';

const Component = () => {
  const [visible, setVisible] = useState(false);
  const { observer, onClose } = useModal({
    onClose: () => setVisible(false)
  });

  return (
    <>
      {visible && (
        <ClayModal
          observer={observer}
          size="lg"
          spritemap={spritemap}
          status="info"
        >
          <ClayModal.Header>{"Title"}</ClayModal.Header>
          <ClayModal.Body>
            <h1>{"Hello world!"}</h1>
          </ClayModal.Body>
          <ClayModal.Footer
            first={
              <ClayButton.Group spaced>
                <ClayButton displayType="secondary">{"Secondary"}</ClayButton>
                <ClayButton displayType="secondary">{"Secondary"}</ClayButton>
              </ClayButton.Group>
            }
            last={<ClayButton onClick={onClose}>{"Primary"}</ClayButton>}
          />
        </ClayModal>
      )}
      <ClayButton displayType="primary" onClick={() => setVisible(true)}>
        {"Open modal"}
      </ClayButton>
    </>
  );
};

render(<Component />);

const Component = () => {
  const [visible, setVisible] = useState(false);
  const { observer, onClose } = useModal({
    onClose: () => setVisible(false)
  });
  return (
    <>
      {visible && (
        <ClayModal
          observer={observer}
          size="lg"
          spritemap={spritemap}
          status="info"
        >
          <ClayModal.Header>{"Title"}</ClayModal.Header>
          <ClayModal.Body>
            <h1>{"Hello world!"}</h1>
          </ClayModal.Body>
          <ClayModal.Footer
            first={
              <ClayButton.Group spaced>
                <ClayButton displayType="secondary">{"Secondary"}</ClayButton>
                <ClayButton displayType="secondary">{"Secondary"}</ClayButton>
              </ClayButton.Group>
            }
            last={<ClayButton onClick={onClose}>{"Primary"}</ClayButton>}
          />
        </ClayModal>
      )}
      <ClayButton displayType="primary" onClick={() => setVisible(true)}>
        {"Open modal"}
      </ClayButton>
    </>
  );
};
render(<Component />);

useModal hook

The useModal hook is required to create a Modal component in Clay, it is responsible for communicating with ClayModal and controlling states to make animations, this is necessary because Modal needs animation when opening and closing so we need to delay calls of the onClose so you can safely control Modal's visibility or do other things.

useModal returns a signature with observer and onClose:

observer - Observer is the communication channel that connects ClayModal with useModal.
onClose - Callback is called after Modal's close animation.

const {observer, onClose} = useModal({
	onClose: () => setVisible(false),
});

To avoid future problems, do not use the information or change the values of `observer`, it is considered a bad practice.

To prevent Modal from closing before animation always use the onClose method returned by useModal.

<ClayModal.Footer
-   last={<ClayButton onClick={() => setVisible(false)}>{"Primary"}</ClayButton>}
+   last={<ClayButton onClick={onClose}>{"Primary"}</ClayButton>}
/>

Usage

useModal is a hook so it implies that you cannot use ClayModal directly in a class component. If you'd like to use it in a class component, try the recommended strategy below.

Wrap ClayModal and useModal in a function component.

const ModalWithDialog = ({visible, onClose, title, body}) => {
    const { observer, onClose: close } = useModal({
        onClose: onVisible,
    });

    if (!visible) {
        return;
    }

    return (
        <ClayModal
            observer={observer}
            spritemap={spritemap}
        >
            <ClayModal.Header>{title}</ClayModal.Header>
            <ClayModal.Body>
                {body}
            </ClayModal.Body>
            <ClayModal.Footer
                last={<ClayButton onClick={close}>{"Close"}</ClayButton>}
            />
        </ClayModal>
    );
};

// This is pseudocode
class Page extends Component {
    render() {
        return (
            <>
                <ModalWithDialog visible={this.state.visible} onClose={() => this.setVisible(false)} title={...} body={...} />
                <ClayButton displayType="primary" onClick={() => this.setVisible(true)}>
                    {"Open modal"}
                </ClayButton>
            <>
        );
    }
}

useModal may be lost if you raise the visible condition above the hook, if Modal happens to be unmounted at the same time as the component. Ideally the hook is not unmounted every time Modal is opened and closed.

ClayModal.Header offers two different APIs for use by toggling the prop withTitle. By default(withTitle={true}), ClayModal.Header behaves like a high-level component. If you want to use the lower-level components in Header, all you need to do is set withTitle={false}.

Here is an example of both APIs:

import ClayIcon from '@clayui/icon';
import ClayButton from '@clayui/button';
import ClayModal, {useModal} from '@clayui/modal';

import ClayIcon from '@clayui/icon';
import ClayButton from '@clayui/button';
import ClayModal, {useModal} from '@clayui/modal';

const Component = () => {
  return (
    <>
      <ClayModal.Header>{"Modal Title"}</ClayModal.Header>

      <br />

      <ClayModal.Header withTitle={false}>
        <ClayModal.ItemGroup>
          <ClayModal.Item>
            <ClayModal.TitleSection>
              <ClayModal.Title>
                <ClayModal.TitleIndicator>
                  <ClayIcon spritemap={spritemap} symbol="info-circle" />
                </ClayModal.TitleIndicator>
                {"Modal Title"}
              </ClayModal.Title>
            </ClayModal.TitleSection>
          </ClayModal.Item>
          <ClayModal.Item shrink>
            <ClayModal.SubtitleSection>
              <ClayModal.Subtitle>{"Modal Subtitle"}</ClayModal.Subtitle>
            </ClayModal.SubtitleSection>
          </ClayModal.Item>
        </ClayModal.ItemGroup>

        <ClayButton
          aria-label="close"
          className="close"
          displayType="unstyled"
          onClick={() => {}}
        >
          <ClayIcon spritemap={spritemap} symbol="times" />
        </ClayButton>
      </ClayModal.Header>
    </>
  );
};

render(<Component />);

const Component = () => {
  return (
    <>
      <ClayModal.Header>{"Modal Title"}</ClayModal.Header>
      <br />
      <ClayModal.Header withTitle={false}>
        <ClayModal.ItemGroup>
          <ClayModal.Item>
            <ClayModal.TitleSection>
              <ClayModal.Title>
                <ClayModal.TitleIndicator>
                  <ClayIcon spritemap={spritemap} symbol="info-circle" />
                </ClayModal.TitleIndicator>
                {"Modal Title"}
              </ClayModal.Title>
            </ClayModal.TitleSection>
          </ClayModal.Item>
          <ClayModal.Item shrink>
            <ClayModal.SubtitleSection>
              <ClayModal.Subtitle>{"Modal Subtitle"}</ClayModal.Subtitle>
            </ClayModal.SubtitleSection>
          </ClayModal.Item>
        </ClayModal.ItemGroup>
        <ClayButton
          aria-label="close"
          className="close"
          displayType="unstyled"
          onClick={() => {}}
        >
          <ClayIcon spritemap={spritemap} symbol="times" />
        </ClayButton>
      </ClayModal.Header>
    </>
  );
};
render(<Component />);

Provider

When your application uses a lot of modals, you can use <ClayModalProvider /> to have only one open Modal on the screen and the component centered on your application, you can invoke the modal from the context through the API. It is not recommended to have multiple modals open at the same time.

Add in the project root:

<ClayModalProvider spritemap={spritemap}>
	<MyApp />
</ClayModalProvider>

In any part of your application you can invoke modal.

import {Context} from '@clayui/modal';
import ClayButton from '@clayui/button';

const MyApp = () => {
	const [state, dispatch] = useContext(Context);

	return (
		<ClayButton
			displayType="primary"
			onClick={() =>
				dispatch({
					payload: {
						body: <h1>{'Hello world!'}</h1>,
						footer: [
							,
							,
							<ClayButton key={3} onClick={state.onClose}>
								{'Primary'}
							</ClayButton>,
						],
						header: 'Title',
						size: 'lg',
					},
					type: 1,
				})
			}
		>
			{'Open modal'}
		</ClayButton>
	);
};

Provider contains two different states that you can control:

Close - 0
Open - 1

The context signature is similar to a useReducer, contains state and dispatch.

const [state, dispatch] = useContext(Context);

dispatch({payload: {...}, type: 1});

state returns all values that are passed to dispatch payload and you can pass body, footer, header, size, status and url to payload.

API

ClayModal

Property	Type	Required	Default	Description
size	Size	false		The size of element modal.
observer	Observer	true		Observer is Modal's communication system with `useModal` hook, adds observer from `useModal` hook here.

ClayModal.Body

Property	Type	Required	Default	Description
iFrameProps	React.HTMLAttributes<HTMLIFrameElement>	false	{}	Props to add to the iframe element
scrollable	boolean	false		Flag to indicate if body should be a fixed height with a scrollable overflow.
url	string	false		Url to place an iframe in the body of the modal.

Property	Type	Required	Description
first	React.ReactElement	false	Sets the elements that are positioned `first following the LTR direction on the footer.
last	React.ReactElement	false	Sets the elements that are positioned `last` following the LTR direction on the footer.
middle	React.ReactElement	false	Sets the elements that are positioned in the middle of the footer.

Property	Type	Required	Default	Description
withTitle	boolean	false	true	Flag for indicating if you want to use the Header its children being the title. Set to `false` if you want to use this as a low-level component.