Alert Dialog

Alert dialogs can be disruptive because they require users to take an action before returning to the application; they should be used thoughtfully and sparingly.

size

AlertDialog can have three sizes: small medium large

Edit in Playroom

const SIZES = ['small', 'medium', 'large'];
const [isOpen, setOpen] = useState(false);
const [size, setSize] = useState(SIZES[0]);
const titleCase = (str) => str.charAt(0).toUpperCase() + str.slice(1);
const actions = {
  confirm: { label: 'Okay', action: () => setOpen(false) },
};
return (
  <Inline gap="medium">
    <SegmentedControl
      onChange={setSize}
      value={size}
      options={SIZES.map((value) => ({ label: titleCase(value), value }))}
    />
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <AlertDialog
      actions={actions}
      isOpen={isOpen}
      title="Hey there"
      size={size}
    >
      <Stack gap="medium">
        <Text>
          You’ve now created 3 of 3 free pay runs. We’re continuing to work hard
          to make this app powerful and easy to use.
        </Text>
        <Text>
          If you find it valuable, please{' '}
          <TextLink href="#">subscribe</TextLink> in your Payroll Mobile App to
          get unlimited pay runs, and much more!
        </Text>
      </Stack>
    </AlertDialog>
  </Inline>
);

Acknowledgment

Acknowledgment dialogs are used when the system requires the user to acknowledge the presented information. It contains only a single action, commonly “Okay”.

Edit in Playroom

const [isOpen, setOpen] = useState(false);
const actions = {
  confirm: { label: 'Okay', action: () => setOpen(false) },
};
return (
  <>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <AlertDialog actions={actions} isOpen={isOpen} title="Hey there">
      <Stack gap="medium">
        <Text>
          You’ve now created 3 of 3 free pay runs. We’re continuing to work hard
          to make this app powerful and easy to use.
        </Text>
        <Text>
          If you find it valuable, please{' '}
          <TextLink href="#">subscribe</TextLink> in your Payroll Mobile App to
          get unlimited pay runs, and much more!
        </Text>
      </Stack>
    </AlertDialog>
  </>
);

Confirmation

Confirmation dialogs are used to confirm significant user decisions. Clearly describe the action being confirmed and explain any potential consequences that it may cause. Both the title and the button should reflect the action that will occur.

The title should in most cases be phrased as a short binary dichotomous question, so that the action is easy and clear to make. Read this UX article for more copywriting direction and tips.

If the confirm action is asynchronous, you may also pass a loading property with the confirm action options to influence the button state.

Edit in Playroom

const [isOpen, setOpen] = useState(false);
const [isLoading, setLoading] = useState(false);
function confirmEdit() {
  setLoading(true);
  setTimeout(() => {
    setLoading(false);
    setOpen(false);
  }, 2000);
}
const actions = {
  confirm: { label: 'Yes, edit', action: confirmEdit, loading: isLoading },
  cancel: { label: 'Cancel', action: () => setOpen(false) },
};
return (
  <>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <AlertDialog actions={actions} isOpen={isOpen} title="Edit pay run?">
      <Text>If you continue, the pay run will be reverted to draft.</Text>
    </AlertDialog>
  </>
);

Critical Confirmation

Critical confirmation dialogs describe destructive or irreversible actions. They are commonly used in situations where confirmation of an action would result in significant data loss if done accidentally.

Edit in Playroom

const [isOpen, setOpen] = useState(false);
const actions = {
  confirm: { label: 'Yes, delete', action: () => setOpen(false) },
  cancel: { label: 'Cancel', action: () => setOpen(false) },
};
return (
  <>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <AlertDialog
      actions={actions}
      isOpen={isOpen}
      title="Delete pay run?"
      tone="critical"
    >
      <Text>This action is permanent and cannot be reversed.</Text>
    </AlertDialog>
  </>
);

Info Dialog

Use info dialogs to communicate impactful information at key moments:

Celebrate the success of a large task
Welcome a new user onboard
Inform users that their free trial has ended

You can use any of our Spot or Hero illustrations in the illustration prop.

Edit in Playroom

const [isOpen, setOpen] = useState(false);
const actions = {
  confirm: { label: 'Continue', action: () => setOpen(false) },
  cancel: { label: 'Cancel', action: () => setOpen(false) },
};
return (
  <>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <InfoDialog
      isOpen={isOpen}
      illustration={<SpotCelebrate />}
      onClose={() => setOpen(false)}
      title="Welcome to Payroll Web!"
      actions={actions}
    >
      <Text color="muted">
        Our plans include Basic (free) and Premium. Our premium plan has many
        great features like leave balances and reports. We’ll start you on a
        premium free trial with no obligations - you can opt out in Settings at
        anytime.
      </Text>
    </InfoDialog>
  </>
);

size

InfoDialog can have three sizes: small medium large

Edit in Playroom

const SIZES = ['small', 'medium', 'large'];
const [isOpen, setOpen] = useState(false);
const [size, setSize] = useState(SIZES[0]);
const titleCase = (str) => str.charAt(0).toUpperCase() + str.slice(1);
const actions = {
  confirm: { label: 'Continue', action: () => setOpen(false) },
  cancel: { label: 'Cancel', action: () => setOpen(false) },
};
return (
  <Inline gap="medium">
    <SegmentedControl
      onChange={setSize}
      value={size}
      options={SIZES.map((value) => ({ label: titleCase(value), value }))}
    />
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <InfoDialog
      isOpen={isOpen}
      illustration={<SpotCelebrate />}
      onClose={() => setOpen(false)}
      title="Welcome to Payroll Web!"
      actions={actions}
      size={size}
    >
      <Text color="muted">
        Our plans include Basic (free) and Premium. Our premium plan has many
        great features like leave balances and reports. We’ll start you on a
        premium free trial with no obligations - you can opt out in Settings at
        anytime.
      </Text>
    </InfoDialog>
  </Inline>
);

Form Dialog

Use form dialogs for supporting tasks that require a handle full of fields to be filled out.

Note: Do not put large forms inside a form dialog. Use side drawer or bottom drawer instead.

Edit in Playroom

const formSchema = field.object({
  firstName: field.text({
    validate: validate((value) => {
      validate.required(value);
      return value;
    }),
  }),
  lastName: field.text({
    validate: validate((value) => {
      validate.required(value);
      return value;
    }),
  }),
});
const [isOpen, setOpen] = useState(false);
const form = useForm(formSchema);
const handleSubmit = useSubmit(form, (value) => {
  console.log(value);
});
return (
  <React.Fragment>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <FormDialog
      actions={{
        confirm: {
          label: 'Save',
          action: handleSubmit,
        },
        cancel: { label: 'Cancel', action: () => setOpen(false) },
      }}
      isOpen={isOpen}
      title="Add contact"
    >
      <FieldStack>
        <Field
          label="First name"
          invalidMessage={form.fields.firstName.props.invalidMessage}
        >
          <TextInput {...form.fields.firstName.props} />
        </Field>
        <Field
          label="Last name"
          invalidMessage={form.fields.lastName.props.invalidMessage}
        >
          <TextInput {...form.fields.lastName.props} />
        </Field>
      </FieldStack>
    </FormDialog>
  </React.Fragment>
);

Content Dialog

Content dialogs are commonly used for short and non-frequent tasks, such as editing or management tasks. If a user needs to repeatably preform a task, consider making the task do-able from the main page.

Note: Do not put forms inside content dialog. Use form dialog instead.

size

ContentDialog can have three sizes: small medium large

Edit in Playroom

const SIZES = ['small', 'medium', 'large'];
const [isOpen, setOpen] = useState(false);
const [size, setSize] = useState(SIZES[0]);
const titleCase = (str) => str.charAt(0).toUpperCase() + str.slice(1);
return (
  <Inline gap="medium">
    <SegmentedControl
      onChange={setSize}
      value={size}
      options={SIZES.map((value) => ({ label: titleCase(value), value }))}
    />
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <ContentDialog
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      size={size}
      header={
        <Box paddingX="xlarge" paddingY="large">
          <Heading level="3">{titleCase(size)} dialog</Heading>
        </Box>
      }
    >
      <Box paddingX="xlarge" paddingY="large">
        <Text>
          Cupcake ipsum dolor sit amet bonbon chocolate cake fruitcake.
          Chocolate bar gummi bears gummi bears jelly beans. Gummi bears cookie
          tart topping. Marshmallow caramels gummies gummies marzipan topping
          brownie pudding.
        </Text>
      </Box>
    </ContentDialog>
  </Inline>
);

Sections

The content dialog is composed of three distinct zones: A header, the body, and a footer.

Edit in Playroom

const [isOpen, setOpen] = useState(false);
return (
  <>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <ContentDialog
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      size="medium"
      header={
        <Box paddingX="xlarge" paddingY="large">
          <Heading level="3">Header section</Heading>
        </Box>
      }
      footer={
        <Box paddingX="xlarge" paddingY="large">
          <Text color="muted" size="small">
            Footer section
          </Text>
        </Box>
      }
    >
      <Box paddingX="xlarge" paddingY="large">
        <Text>Body section</Text>
      </Box>
    </ContentDialog>
  </>
);

Overflow

The content dialog will fill the available vertical space. When this happens the "body" section will become scrollable.

Edit in Playroom

const [isOpen, setOpen] = useState(false);
return (
  <>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <ContentDialog
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      size="medium"
      header={
        <Box paddingX="xlarge" paddingY="large">
          <Heading level="3">Overflow example</Heading>
        </Box>
      }
      footer={
        <Inline align="right" paddingX="xlarge" paddingY="large">
          <Button onClick={() => setOpen(false)} label="Close" />
        </Inline>
      }
    >
      <Stack gap="large" paddingX="xlarge" paddingY="large">
        <Text>
          Cupcake ipsum dolor sit amet bonbon chocolate cake fruitcake.
          Chocolate bar gummi bears gummi bears jelly beans. Gummi bears cookie
          tart topping. Marshmallow caramels gummies gummies marzipan topping
          brownie pudding. Marshmallow gummies candy pie pastry gummi bears.
          Sweet topping pudding. Candy tootsie roll lollipop dessert icing jelly
          beans. Sweet ice cream cake carrot cake. Cheesecake sesame snaps
          croissant toffee toffee. Macaroon donut apple pie cake tart
          gingerbread. Croissant cookie halvah chupa chups tootsie roll tart.
          Dragée cupcake cake brownie sesame snaps sugar plum bear claw. Powder
          cookie cupcake topping sesame snaps dragée halvah wafer tiramisu.
        </Text>
        <Text>
          Wafer lollipop icing pudding biscuit. Lemon drops jelly beans cupcake
          candy cotton candy candy canes jelly marshmallow. Apple pie bear claw
          powder sesame snaps macaroon brownie jelly beans halvah pastry.
          Lollipop cookie chocolate cake gingerbread lollipop dessert powder
          jujubes. Powder icing jelly-o sesame snaps chocolate bar cookie apple
          pie cookie fruitcake. Cotton candy danish halvah chocolate cake candy
          jujubes cupcake cotton candy chocolate. Tiramisu cupcake gummies
          caramels tiramisu chocolate bar chocolate cake carrot cake. Biscuit
          pie sweet cotton candy lollipop halvah. Chocolate cake cake topping
          candy canes. Wafer marzipan croissant pudding sugar plum. Sweet roll
          sesame snaps cheesecake macaroon. Cotton candy marzipan carrot cake
          liquorice chocolate pastry pie cotton candy. Chupa chups halvah sesame
          snaps macaroon.
        </Text>
        <Text>
          Jujubes cheesecake tart pudding chocolate. Dragée gummies tootsie roll
          gummi bears sweet roll cotton candy dragée fruitcake. Marshmallow
          jelly-o lollipop chupa chups. Lollipop ice cream powder. Biscuit icing
          sweet croissant cheesecake sweet roll. Croissant caramels halvah
          macaroon jelly beans icing wafer. Sweet roll tart icing gummies donut
          chupa chups macaroon marshmallow. Croissant cookie muffin jelly beans.
          Croissant cupcake carrot cake pastry dessert biscuit sweet. Chocolate
          brownie croissant biscuit oat cake powder tiramisu. Topping candy
          canes halvah chocolate bar cotton candy donut gummi bears. Powder
          gummi bears cupcake macaroon tootsie roll ice cream pie. Danish candy
          canes candy marshmallow macaroon soufflé pie sweet donut. Jujubes
          cheesecake macaroon apple pie gingerbread cheesecake apple pie
          brownie.
        </Text>
        <Text>
          Muffin ice cream gummies cake jujubes dragée sweet roll. Bonbon
          topping sesame snaps macaroon chocolate jelly. Icing lollipop toffee
          dessert icing. Chupa chups chocolate bar croissant soufflé topping.
          Cake donut marzipan biscuit cake wafer. Caramels jelly-o marzipan
          chupa chups caramels halvah. Ice cream muffin chocolate jelly muffin
          pie pudding cake. Muffin candy gingerbread apple pie. Jelly beans
          liquorice cake bonbon. Dragée danish pie croissant sweet. Tart dragée
          croissant liquorice. Tiramisu chocolate bar apple pie donut sweet oat
          cake. Cake icing croissant jujubes dragée chocolate cake fruitcake
          sesame snaps. Chupa chups liquorice jelly tootsie roll tootsie roll
          oat cake.
        </Text>
        <Text>
          Tart wafer gingerbread cake. Lollipop tiramisu donut jelly pie pie
          liquorice biscuit. Biscuit pastry gummies sesame snaps sweet.
          Marshmallow donut marzipan croissant bear claw muffin tiramisu
          gingerbread. Bear claw candy canes marzipan cake croissant jelly
          sweet. Donut dragée tiramisu sweet. Halvah chocolate cake sugar plum
          chupa chups topping cookie. Pudding gummi bears pastry pudding gummi
          bears apple pie pudding. Chocolate bar jelly sweet roll lollipop bear
          claw brownie cookie chupa chups. Bear claw tootsie roll cake chocolate
          dessert liquorice candy soufflé sweet. Soufflé chupa chups chocolate
          cake ice cream. Cotton candy gingerbread soufflé candy powder
          gingerbread. Marzipan soufflé cotton candy. Oat cake jujubes icing
          sesame snaps pie.
        </Text>
      </Stack>
    </ContentDialog>
  </>
);

Passive Dialog

Passive dialog is used when you want to block the screen while a critical process is happening in the background that shoud not be interrupted such as saving a long list of items or a payment operation.

A passive dialog cannot be closed by the user, it must be close programatically after the background process is complete.

Edit in Playroom

const [isOpen, setOpen] = useState(false);
return (
  <React.Fragment>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <PassiveDialog isOpen={isOpen} title="Saving items">
      <Stack
        gap="large"
        height="100%"
        css={{
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <Text>2 of 3 </Text>
        <LoadingDots label="Saving items" />
      </Stack>
    </PassiveDialog>
  </React.Fragment>
);

size

PassiveDialog can have three sizes: small medium large

Edit in Playroom

const SIZES = ['small', 'medium', 'large'];
const [isOpen, setOpen] = useState(false);
const [size, setSize] = useState(SIZES[0]);
const titleCase = (str) => str.charAt(0).toUpperCase() + str.slice(1);
return (
  <Inline gap="medium">
    <SegmentedControl
      onChange={setSize}
      value={size}
      options={SIZES.map((value) => ({ label: titleCase(value), value }))}
    />
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <PassiveDialog isOpen={isOpen} title="Saving items" size={size}>
      <Stack
        gap="large"
        height="100%"
        css={{
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <Text>2 of 3 </Text>
        <LoadingDots label="Saving items" />
      </Stack>
    </PassiveDialog>
  </Inline>
);

Blank Dialog

Has no opinions about content, render whatever you need as children.

Note: This should be used in exceptional cases. Consider using one of the other dialogs before reaching for a blank dialog.

Edit in Playroom

const { spacing } = useTheme();
const [isOpen, setOpen] = useState(false);
const gutter = spacing.small * 2;
return (
  <>
    <ActionButton onClick={() => setOpen(true)} label="Open dialog" />
    <BlankDialog isOpen={isOpen} onClose={() => setOpen(false)}>
      <Box
        width={`calc(100vw - ${gutter}px)`}
        height={`calc(100vh - ${gutter}px)`}
        padding="large"
      >
        <ActionButton label="Close" onClick={() => setOpen(false)} />
      </Box>
    </BlankDialog>
  </>
);

Modal Dialog

size

Acknowledgment

Confirmation

Critical Confirmation

Info Dialog

size

Form Dialog

Content Dialog

size

Sections

Overflow

Passive Dialog

size

Blank Dialog