 <Dialog.Root>
  <Dialog.Trigger>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Header
      title="Edit profile"
      description="Make changes to your profile here. Click save when you’re done."
    />

    <Dialog.Body>
      <Flex direction="column" gap="4">
        <label>
          <Text as="div" size="2" mb="2" weight="bold">
            Name
          </Text>
          <TextField.Root
            defaultValue="Jane Doe"
            placeholder="Enter your full name"
          />
        </label>

        <label>
          <Text as="div" size="2" mb="2" weight="bold">
            Email
          </Text>
          <TextField.Root
            defaultValue="jane@foo-corp.com"
            placeholder="Enter your email"
          />
        </label>
      </Flex>
    </Dialog.Body>

    <Dialog.Footer>
      <Dialog.Close>
        <Button>Cancel</Button>
      </Dialog.Close>
      <Dialog.Close>
        <Button color="purple">Save</Button>
      </Dialog.Close>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>

Props

Dialog.Body

`indicators`

nonexyleftrighttopbottomall

Also supports MarginProps: `m`, `mb`, `ml`, `mr`, `mt`, `mx`, `my`

Dialog.Content

`align`

centerstart

`asChild`

boolean

Composes the component into its immediate child instead of rendering its own HTML element. You’ll have to provide a single React Element child.

`container`

Element | DocumentFragment | null

`height`

Responsive<string>

`maxHeight`

Responsive<string>

`maxWidth`

Responsive<string>

Sets the CSS **max-width** property. Supports CSS strings and responsive objects.

`minHeight`

Responsive<string>

`minWidth`

Responsive<string>

Sets the CSS **min-width** property. Supports CSS strings and responsive objects.

`size`

123456

Default: 3

`width`

Responsive<string>

Sets the CSS **width** property. Supports CSS strings and responsive objects.

Dialog.Description

`align`

centerleftright

`color`

rubygraygoldbronzebrownyellowamberorangetomatoredcrimsonpinkplumpurplevioletirisindigobluecyantealjadegreengrasslimemintsky

`highContrast`

boolean

`size`

123456789

`trim`

endnormalbothstart

`truncate`

boolean

`weight`

boldmediumlightregular

`wrap`

wrapnowrapprettybalance

Also supports MarginProps: `m`, `mb`, `ml`, `mr`, `mt`, `mx`, `my`

Dialog.Header

`title`

required

ReactNode

`description`

ReactNode

`error`

ReactNode

Also supports MarginProps: `m`, `mb`, `ml`, `mr`, `mt`, `mx`, `my`

Dialog.Title

`align`

centerleftright

`as`

h1h2h3h4h5h6

`color`

rubygraygoldbronzebrownyellowamberorangetomatoredcrimsonpinkplumpurplevioletirisindigobluecyantealjadegreengrasslimemintsky

`highContrast`

boolean

`size`

123456789

`trim`

endnormalbothstart

`truncate`

boolean

`weight`

boldmediumlightregular

`wrap`

wrapnowrapprettybalance

Also supports MarginProps: `m`, `mb`, `ml`, `mr`, `mt`, `mx`, `my`

Usage

Sizes

Use the size prop in the Content component to control the maxWidth of the dialog. If you have a very specific case, you can still pass a custom maxWidth prop to override the size.

 <Flex gap="4">
  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Size 1</Button>
    </Dialog.Trigger>
    <Dialog.Content size="1">
      <Dialog.Header
        title="Edit profile"
        description="Make changes to your profile here. Click save when you’re done."
      />

      <Dialog.Body>
        <Text as="p">
          Three fundamental aspects of typography are legibility, readability,
          and aesthetics. Although in a non-technical sense “legible” and
          “readable” are often used synonymously, typographically they are
          separate but related concepts.
        </Text>
      </Dialog.Body>

      <Dialog.Footer>
        <Dialog.Close>
          <Button>Cancel</Button>
        </Dialog.Close>
        <Dialog.Close>
          <Button color="purple">Save</Button>
        </Dialog.Close>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>

  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Size 2</Button>
    </Dialog.Trigger>
    <Dialog.Content size="2">
      <Dialog.Header
        title="Edit profile"
        description="Make changes to your profile here. Click save when you’re done."
      />

      <Dialog.Body>
        <Text as="p">
          Three fundamental aspects of typography are legibility, readability,
          and aesthetics. Although in a non-technical sense “legible” and
          “readable” are often used synonymously, typographically they are
          separate but related concepts.
        </Text>
      </Dialog.Body>

      <Dialog.Footer>
        <Dialog.Close>
          <Button>Cancel</Button>
        </Dialog.Close>
        <Dialog.Close>
          <Button color="purple">Save</Button>
        </Dialog.Close>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>

  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Size 3</Button>
    </Dialog.Trigger>
    <Dialog.Content size="3">
      <Dialog.Header
        title="Edit profile"
        description="Make changes to your profile here. Click save when you’re done."
      />

      <Dialog.Body>
        <Text as="p">
          Three fundamental aspects of typography are legibility, readability,
          and aesthetics. Although in a non-technical sense “legible” and
          “readable” are often used synonymously, typographically they are
          separate but related concepts.
        </Text>
      </Dialog.Body>

      <Dialog.Footer>
        <Dialog.Close>
          <Button>Cancel</Button>
        </Dialog.Close>
        <Dialog.Close>
          <Button color="purple">Save</Button>
        </Dialog.Close>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>

  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Size 4</Button>
    </Dialog.Trigger>
    <Dialog.Content size="4">
      <Dialog.Header
        title="Edit profile"
        description="Make changes to your profile here. Click save when you’re done."
      />

      <Dialog.Body>
        <Text as="p">
          Three fundamental aspects of typography are legibility, readability,
          and aesthetics. Although in a non-technical sense “legible” and
          “readable” are often used synonymously, typographically they are
          separate but related concepts.
        </Text>
      </Dialog.Body>

      <Dialog.Footer>
        <Dialog.Close>
          <Button>Cancel</Button>
        </Dialog.Close>
        <Dialog.Close>
          <Button color="purple">Save</Button>
        </Dialog.Close>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>

  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Size 5</Button>
    </Dialog.Trigger>
    <Dialog.Content size="5">
      <Dialog.Header
        title="Edit profile"
        description="Make changes to your profile here. Click save when you’re done."
      />

      <Dialog.Body>
        <Text as="p">
          Three fundamental aspects of typography are legibility, readability,
          and aesthetics. Although in a non-technical sense “legible” and
          “readable” are often used synonymously, typographically they are
          separate but related concepts.
        </Text>
      </Dialog.Body>

      <Dialog.Footer>
        <Dialog.Close>
          <Button>Cancel</Button>
        </Dialog.Close>
        <Dialog.Close>
          <Button color="purple">Save</Button>
        </Dialog.Close>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>

  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Size 6</Button>
    </Dialog.Trigger>
    <Dialog.Content size="6">
      <Dialog.Header
        title="Edit profile"
        description="Make changes to your profile here. Click save when you’re done."
      />

      <Dialog.Body>
        <Text as="p">
          Three fundamental aspects of typography are legibility, readability,
          and aesthetics. Although in a non-technical sense “legible” and
          “readable” are often used synonymously, typographically they are
          separate but related concepts.
        </Text>
      </Dialog.Body>

      <Dialog.Footer>
        <Dialog.Close>
          <Button>Cancel</Button>
        </Dialog.Close>
        <Dialog.Close>
          <Button color="purple">Save</Button>
        </Dialog.Close>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>

  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Fit</Button>
    </Dialog.Trigger>
    <Dialog.Content>
      <Dialog.Header
        title="Edit profile"
        description="Make changes to your profile here. Click save when you’re done."
      />

      <Dialog.Body>
        <Text as="p">
          Three fundamental aspects of typography are legibility, readability,
          and aesthetics. Although in a non-technical sense “legible” and
          “readable” are often used synonymously, typographically they are
          separate but related concepts.
        </Text>
      </Dialog.Body>

      <Dialog.Footer>
        <Dialog.Close>
          <Button>Cancel</Button>
        </Dialog.Close>
        <Dialog.Close>
          <Button color="purple">Save</Button>
        </Dialog.Close>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>
</Flex>

With Inset

Use the Inset component to create a container that ignores the Content part padding. If needed, you can recreate the original padding by setting the Inset part’s padding props to "current".

 <Dialog.Root>
  <Dialog.Trigger>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content width="500px">
    <Dialog.Header
      title="Custom domain"
      description="Customize the domain used to authenticate users."
    />

    <Dialog.Body>
      <Box>
        <Label mb="1">Auth domain</Label>
        <TextField.Root disabled defaultValue="auth.workos.com" />
      </Box>
    </Dialog.Body>

    <Inset
      p="current"
      side="bottom"
      style={{
        backgroundColor: 'var(--gray-a1)',
        borderTop: '1px solid var(--gray-a4)',
      }}
    >
      <Dialog.Footer>
        <Text size="2" color="gray" mr="auto">
          <Link href="https://example.com" color="gray" highContrast>
            Upgrade to Enterprise
          </Link>{' '}
          to enable this feature
        </Text>

        <Dialog.Close>
          <Button>Cancel</Button>
        </Dialog.Close>
        <Dialog.Close>
          <Button disabled>Save</Button>
        </Dialog.Close>
      </Dialog.Footer>
    </Inset>
  </Dialog.Content>
</Dialog.Root>

With scrollable content

Whenever the body of the dialog is bigger than the dialog itself, it will show a scrollbar automatically.

 <Dialog.Root>
  <Dialog.Trigger>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content size="3">
    <Dialog.Header title="Heading" description="Subtitle" />

    <Dialog.Body>
      <Text as="p" mb="4">
        Three fundamental aspects of typography are legibility, readability, and
        aesthetics. Although in a non-technical sense “legible” and “readable”
        are often used synonymously, typographically they are separate but
        related concepts.
      </Text>

      <Text as="p" mb="4">
        Legibility describes how easily individual characters can be
        distinguished from one another. It is described by Walter Tracy as “the
        quality of being decipherable and recognisable”. For instance, if a “b”
        and an “h”, or a “3” and an “8”, are difficult to distinguish at small
        sizes, this is a problem of legibility.
      </Text>

      <Text as="p" mb="4">
        Typographers are concerned with legibility insofar as it is their job to
        select the correct font to use. Brush Script is an example of a font
        containing many characters that might be difficult to distinguish. The
        selection of cases influences the legibility of typography because using
        only uppercase letters (all-caps) reduces legibility.
      </Text>

      <Text as="p" mb="4">
        Three fundamental aspects of typography are legibility, readability, and
        aesthetics. Although in a non-technical sense “legible” and “readable”
        are often used synonymously, typographically they are separate but
        related concepts.
      </Text>

      <Text as="p" mb="4">
        Legibility describes how easily individual characters can be
        distinguished from one another. It is described by Walter Tracy as “the
        quality of being decipherable and recognisable”. For instance, if a “b”
        and an “h”, or a “3” and an “8”, are difficult to distinguish at small
        sizes, this is a problem of legibility.
      </Text>

      <Text as="p" mb="4">
        Three fundamental aspects of typography are legibility, readability, and
        aesthetics. Although in a non-technical sense “legible” and “readable”
        are often used synonymously, typographically they are separate but
        related concepts.
      </Text>

      <Text as="p" mb="4">
        Legibility describes how easily individual characters can be
        distinguished from one another. It is described by Walter Tracy as “the
        quality of being decipherable and recognisable”. For instance, if a “b”
        and an “h”, or a “3” and an “8”, are difficult to distinguish at small
        sizes, this is a problem of legibility.
      </Text>

      <Text as="p" mb="4">
        Typographers are concerned with legibility insofar as it is their job to
        select the correct font to use. Brush Script is an example of a font
        containing many characters that might be difficult to distinguish. The
        selection of cases influences the legibility of typography because using
        only uppercase letters (all-caps) reduces legibility.
      </Text>

      <Text as="p" mb="4">
        Three fundamental aspects of typography are legibility, readability, and
        aesthetics. Although in a non-technical sense “legible” and “readable”
        are often used synonymously, typographically they are separate but
        related concepts.
      </Text>

      <Text as="p" mb="4">
        Legibility describes how easily individual characters can be
        distinguished from one another. It is described by Walter Tracy as “the
        quality of being decipherable and recognisable”. For instance, if a “b”
        and an “h”, or a “3” and an “8”, are difficult to distinguish at small
        sizes, this is a problem of legibility.
      </Text>

      <Text as="p">
        Typographers are concerned with legibility insofar as it is their job to
        select the correct font to use. Brush Script is an example of a font
        containing many characters that might be difficult to distinguish. The
        selection of cases influences the legibility of typography because using
        only uppercase letters (all-caps) reduces legibility.
      </Text>
    </Dialog.Body>

    <Dialog.Footer>
      <Dialog.Close>
        <Button>Cancel</Button>
      </Dialog.Close>
      <Dialog.Close>
        <Button disabled>Save</Button>
      </Dialog.Close>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>

With an error callout

 <Dialog.Root>
  <Dialog.Trigger>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content maxWidth="500px">
    <Dialog.Header
      title="Edit profile"
      description="Make changes to your profile here. Click save when you’re done."
      error="Something went wrong. Try again later."
    />

    <Dialog.Body>
      <Flex direction="column" gap="4">
        <label>
          <Text as="div" size="2" mb="2" weight="bold">
            Name
          </Text>
          <TextField.Root
            defaultValue="Jane Doe"
            placeholder="Enter your full name"
          />
        </label>

        <label>
          <Text as="div" size="2" mb="2" weight="bold">
            Email
          </Text>
          <TextField.Root
            defaultValue="jane@foo-corp.com"
            placeholder="Enter your email"
          />
        </label>
      </Flex>
    </Dialog.Body>

    <Dialog.Footer>
      <Dialog.Close>
        <Button>Cancel</Button>
      </Dialog.Close>
      <Dialog.Close>
        <Button color="purple">Save</Button>
      </Dialog.Close>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>

With body scroll Deprecated

This is now deprecated. You should combine the Header, Body and Footer parts to create a scrollable content. So this example is only for reference as most of our dialogs in the dashboard still use this type of dialog.

 <Dialog.Root>
  <Dialog.Trigger>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content size="3">
    <Dialog.Title>Heading</Dialog.Title>
    <Dialog.Description>Subtitle</Dialog.Description>

    <Box mt="4">
      <Text as="p" mb="4">
        Three fundamental aspects of typography are legibility, readability, and
        aesthetics. Although in a non-technical sense “legible” and “readable”
        are often used synonymously, typographically they are separate but
        related concepts.
      </Text>

      <Text as="p" mb="4">
        Legibility describes how easily individual characters can be
        distinguished from one another. It is described by Walter Tracy as “the
        quality of being decipherable and recognisable”. For instance, if a “b”
        and an “h”, or a “3” and an “8”, are difficult to distinguish at small
        sizes, this is a problem of legibility.
      </Text>

      <Text as="p" mb="4">
        Typographers are concerned with legibility insofar as it is their job to
        select the correct font to use. Brush Script is an example of a font
        containing many characters that might be difficult to distinguish. The
        selection of cases influences the legibility of typography because using
        only uppercase letters (all-caps) reduces legibility.
      </Text>

      <Text as="p" mb="4">
        Three fundamental aspects of typography are legibility, readability, and
        aesthetics. Although in a non-technical sense “legible” and “readable”
        are often used synonymously, typographically they are separate but
        related concepts.
      </Text>

      <Text as="p" mb="4">
        Legibility describes how easily individual characters can be
        distinguished from one another. It is described by Walter Tracy as “the
        quality of being decipherable and recognisable”. For instance, if a “b”
        and an “h”, or a “3” and an “8”, are difficult to distinguish at small
        sizes, this is a problem of legibility.
      </Text>

      <Text as="p" mb="4">
        Three fundamental aspects of typography are legibility, readability, and
        aesthetics. Although in a non-technical sense “legible” and “readable”
        are often used synonymously, typographically they are separate but
        related concepts.
      </Text>

      <Text as="p" mb="4">
        Legibility describes how easily individual characters can be
        distinguished from one another. It is described by Walter Tracy as “the
        quality of being decipherable and recognisable”. For instance, if a “b”
        and an “h”, or a “3” and an “8”, are difficult to distinguish at small
        sizes, this is a problem of legibility.
      </Text>

      <Text as="p" mb="4">
        Typographers are concerned with legibility insofar as it is their job to
        select the correct font to use. Brush Script is an example of a font
        containing many characters that might be difficult to distinguish. The
        selection of cases influences the legibility of typography because using
        only uppercase letters (all-caps) reduces legibility.
      </Text>

      <Text as="p" mb="4">
        Three fundamental aspects of typography are legibility, readability, and
        aesthetics. Although in a non-technical sense “legible” and “readable”
        are often used synonymously, typographically they are separate but
        related concepts.
      </Text>

      <Text as="p" mb="4">
        Legibility describes how easily individual characters can be
        distinguished from one another. It is described by Walter Tracy as “the
        quality of being decipherable and recognisable”. For instance, if a “b”
        and an “h”, or a “3” and an “8”, are difficult to distinguish at small
        sizes, this is a problem of legibility.
      </Text>

      <Text as="p">
        Typographers are concerned with legibility insofar as it is their job to
        select the correct font to use. Brush Script is an example of a font
        containing many characters that might be difficult to distinguish. The
        selection of cases influences the legibility of typography because using
        only uppercase letters (all-caps) reduces legibility.
      </Text>
    </Box>

    <Dialog.Footer>
      <Dialog.Close>
        <Button>Cancel</Button>
      </Dialog.Close>
      <Dialog.Close>
        <Button disabled>Save</Button>
      </Dialog.Close>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>

With tables

There are a couple ways to use tables inside dialogs.

You can use the Inset component without Table.Root for an edge-to-edge design
Use with the Table.Root for a contained table look.

 <Dialog.Root>
  <Dialog.Trigger>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Header
      title="Edit profile"
      description="Make changes to your profile here. Click save when you're done."
    />

    <Dialog.Body>
      <Heading size="3" mb="2" as="h3">
        With inset
      </Heading>
      <Inset side="x">
        <Table.Content>
          <Table.Header>
            <Table.Row>
              <Table.ColumnHeader>Device</Table.ColumnHeader>
              <Table.ColumnHeader>Location</Table.ColumnHeader>
            </Table.Row>
          </Table.Header>
          <Table.Body>
            <Table.Row>
              <Table.RowHeader>iPhone Xs</Table.RowHeader>
              <Table.Cell>Sant Cugat del Vallès, Spain</Table.Cell>
            </Table.Row>
            <Table.Row>
              <Table.RowHeader>MacBook Pro 15″</Table.RowHeader>
              <Table.Cell>Sant Cugat del Vallès, Spain</Table.Cell>
            </Table.Row>
          </Table.Body>
        </Table.Content>
      </Inset>

      <Heading size="3" mb="2" mt="6" as="h3">
        Without inset and with Table.Root
      </Heading>
      <Table.Root>
        <Table.Content>
          <Table.Header>
            <Table.Row>
              <Table.ColumnHeader>Device</Table.ColumnHeader>
              <Table.ColumnHeader>Location</Table.ColumnHeader>
            </Table.Row>
          </Table.Header>
          <Table.Body>
            <Table.Row>
              <Table.RowHeader>iPhone Xs</Table.RowHeader>
              <Table.Cell>Sant Cugat del Vallès, Spain</Table.Cell>
            </Table.Row>
            <Table.Row>
              <Table.RowHeader>MacBook Pro 15″</Table.RowHeader>
              <Table.Cell>Sant Cugat del Vallès, Spain</Table.Cell>
            </Table.Row>
          </Table.Body>
        </Table.Content>
      </Table.Root>
    </Dialog.Body>

    <Dialog.Footer>
      <Dialog.Close>
        <Button>Cancel</Button>
      </Dialog.Close>
      <Dialog.Close>
        <Button color="purple">Save</Button>
      </Dialog.Close>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>

Using with forms

Dialogs commonly contain forms for creating or editing resources. These patterns demonstrate proper state management for loading, dirty checking, and error handling using React Hook Form.

Error handling

Demonstrates how to display form submit errors within dialogs.

 () => {
  const [isOpen, setIsOpen] = React.useState(false);

  const form = useForm({
    resolver: zodResolver(
      z.object({
        email: z
          .string()
          .min(1, 'Email is required')
          .email('Invalid email address'),
      }),
    ),
    defaultValues: { email: '' },
  });

  React.useEffect(() => {
    if (isOpen) {
      form.reset();
      form.clearErrors();
    }
  }, [isOpen, form]);

  const onSubmit = async (data) => {
    try {
      await new Promise((resolve) => setTimeout(resolve, 1000));

      // Simulate server error
      if (data.email === 'taken@example.com') {
        form.setError('root', {
          message: 'This email address is already in use',
        });
        return;
      }

      console.log('Success:', data);
      setIsOpen(false);
    } catch (error) {
      form.setError('root', { message: 'Something went wrong' });
    }
  };

  return (
    <Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
      <Dialog.Trigger>
        <Button>Test error handling</Button>
      </Dialog.Trigger>
      <Dialog.Content size="2">
        <FormProvider {...form}>
          <Dialog.Header
            title="Test form errors"
            description="Try 'taken@example.com' to see a server error"
            error={form.formState.errors.root?.message}
          />

          <Dialog.Body>
            <form
              id="test-error-form"
              noValidate
              onSubmit={form.handleSubmit(onSubmit)}
            >
              <Flex direction="column" gap="4">
                <label>
                  <Text as="div" size="2" mb="2" weight="bold">
                    Email
                  </Text>
                  <TextField.Root
                    placeholder="Enter your email"
                    {...form.register('email')}
                    invalid={!!form.formState.errors.email}
                  />
                  {form.formState.errors.email && (
                    <Text size="2" color="red" mt="2">
                      {form.formState.errors.email.message}
                    </Text>
                  )}
                </label>
              </Flex>
            </form>
          </Dialog.Body>

          <Dialog.Footer>
            <Dialog.Close>
              <Button>Cancel</Button>
            </Dialog.Close>
            <Button
              type="submit"
              form="test-error-form"
              color="purple"
              loading={
                form.formState.isSubmitting || form.formState.isSubmitSuccessful
              }
            >
              Submit
            </Button>
          </Dialog.Footer>
        </FormProvider>
      </Dialog.Content>
    </Dialog.Root>
  );
};

Form patterns

The loading state should always be true when the form is submitted or when the submission has succeeded AND the dialog has been closed

 tsx
<Button
  type="submit"
  loading={form.formState.isSubmitting || form.formState.isSubmitSuccessful}
>
  Save changes
</Button>

For edit forms only, keep the submit button disabled when the form is not dirty:

 <Button
  type="submit"
  disabled={!form.formState.isDirty}
  loading={form.formState.isSubmitting}
>
  Save changes
</Button>

Form reset on dialog open

 React.useEffect(() => {
  if (isOpen) {
    form.reset();
    form.clearErrors();
  }
}, [isOpen, form]);

Form structure and errors

Place the <form> tag inside Dialog.Body and use the form attribute on submit buttons. Display form-level errors using the Dialog.Header error prop:

 <Dialog.Content>
  <Dialog.Header
    title="Form title"
    error={form.formState.errors.root?.message}
  />

  <Dialog.Body>
    <form id="my-form" onSubmit={form.handleSubmit(onSubmit)}>
      {/* form fields */}
    </form>
  </Dialog.Body>

  <Dialog.Footer>
    <Button type="submit" form="my-form">
      Submit
    </Button>
  </Dialog.Footer>
</Dialog.Content>

This approach:

Preserves the dialog’s flex layout structure
Displays errors prominently in the header

Field-level validation

Use your resolver (like Zod) for field validation, and display errors inline.

For simple forms (using register):

 <label>
  <Text as="div" size="2" mb="2" weight="bold">
    Email
  </Text>
  <TextField.Root
    {...form.register('email')}
    placeholder="Enter your email"
    invalid={!!form.formState.errors.email}
  />
  {form.formState.errors.email && (
    <Text size="2" color="red" mt="2">
      {form.formState.errors.email.message}
    </Text>
  )}
</label>

For edit forms or when you need more control (using Controller):

 <Controller
  name="email"
  control={form.control}
  render={({ field, fieldState }) => (
    <label>
      <Text as="div" size="2" mb="2" weight="bold">
        Email
      </Text>
      <TextField.Root
        {...field}
        placeholder="Enter your email"
        invalid={!!fieldState.error}
      />
      {fieldState.error && (
        <Text size="2" as="p" color="red" mt="2">
          {fieldState.error.message}
        </Text>
      )}
    </label>
  )}
/>

Recipes

Add resource dialog

A complete example showing how to create a dialog for adding new resources with proper form reset and loading states.

 () => {
  const [isOpen, setIsOpen] = React.useState(false);

  const form = useForm({
    resolver: zodResolver(
      z.object({
        name: z.string().min(1, 'Name is required'),
        email: z.string().min(1, 'Email is required').email('Invalid email'),
      }),
    ),
    defaultValues: { name: '', email: '' },
  });

  // Reset form when dialog opens
  React.useEffect(() => {
    if (isOpen) {
      form.reset();
      form.clearErrors();
    }
  }, [isOpen, form]);

  const onSubmit = async (data) => {
    try {
      // Simulate API call
      await new Promise((resolve) => setTimeout(resolve, 2000));
      console.log('Creating resource:', data);
      setIsOpen(false);
    } catch (error) {
      form.setError('root', { message: 'Failed to create user' });
    }
  };

  return (
    <Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
      <Dialog.Trigger>
        <Button>Create user</Button>
      </Dialog.Trigger>
      <Dialog.Content size="2">
        <FormProvider {...form}>
          <Dialog.Header
            title="Create user"
            description="Enter the user's information below"
            error={form.formState.errors.root?.message}
          />

          <Dialog.Body>
            <form
              id="add-resource-form"
              noValidate
              onSubmit={form.handleSubmit(onSubmit)}
            >
              <Flex direction="column" gap="4">
                <Controller
                  name="name"
                  control={form.control}
                  render={({ field, fieldState }) => (
                    <label>
                      <Text as="div" size="2" mb="2" weight="bold">
                        Name
                      </Text>
                      <TextField.Root
                        {...field}
                        placeholder="Enter the name"
                        invalid={!!fieldState.error}
                      />
                      {fieldState.error && (
                        <Text size="2" as="p" color="red" mt="2">
                          {fieldState.error.message}
                        </Text>
                      )}
                    </label>
                  )}
                />

                <Controller
                  name="email"
                  control={form.control}
                  render={({ field, fieldState }) => (
                    <label>
                      <Text as="div" size="2" mb="2" weight="bold">
                        Email
                      </Text>
                      <TextField.Root
                        {...field}
                        placeholder="Enter the email"
                        invalid={!!fieldState.error}
                      />
                      {fieldState.error && (
                        <Text size="2" as="p" color="red" mt="2">
                          {fieldState.error.message}
                        </Text>
                      )}
                    </label>
                  )}
                />
              </Flex>
            </form>
          </Dialog.Body>

          <Dialog.Footer>
            <Dialog.Close>
              <Button>Cancel</Button>
            </Dialog.Close>
            <Button
              type="submit"
              form="add-resource-form"
              color="purple"
              loading={
                form.formState.isSubmitting || form.formState.isSubmitSuccessful
              }
            >
              Create user
            </Button>
          </Dialog.Footer>
        </FormProvider>
      </Dialog.Content>
    </Dialog.Root>
  );
};

Edit resource dialog

For editing existing resources, the submit button should be disabled when the form is not dirty (no changes made).

 () => {
  const existingResource = {
    name: 'John Adams',
    email: 'john.adams@example.com',
  };
  const [isOpen, setIsOpen] = React.useState(false);

  const form = useForm({
    resolver: zodResolver(
      z.object({
        name: z.string().min(1, 'Name is required'),
        email: z.string().min(1, 'Email is required').email('Invalid email'),
      }),
    ),
    defaultValues: existingResource,
  });

  // Reset form when dialog opens
  React.useEffect(() => {
    if (isOpen) {
      form.reset();
      form.clearErrors();
    }
  }, [isOpen, form]);

  const onSubmit = async (data) => {
    try {
      // Simulate API call
      await new Promise((resolve) => setTimeout(resolve, 2000));
      console.log('Updating resource:', data);
      setIsOpen(false);
    } catch (error) {
      form.setError('root', { message: 'Failed to update user' });
    }
  };

  return (
    <Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
      <Dialog.Trigger>
        <Button>Edit user</Button>
      </Dialog.Trigger>
      <Dialog.Content size="2">
        <FormProvider {...form}>
          <Dialog.Header
            title="Edit user"
            description="Update user information"
            error={form.formState.errors.root?.message}
          />

          <Dialog.Body>
            <form
              id="edit-resource-form"
              noValidate
              onSubmit={form.handleSubmit(onSubmit)}
            >
              <Flex direction="column" gap="4">
                <Controller
                  name="name"
                  control={form.control}
                  render={({ field, fieldState }) => (
                    <label>
                      <Text as="div" size="2" mb="2" weight="bold">
                        Name
                      </Text>
                      <TextField.Root
                        {...field}
                        placeholder="Enter the name"
                        invalid={!!fieldState.error}
                      />
                      {fieldState.error && (
                        <Text size="2" as="p" color="red" mt="2">
                          {fieldState.error.message}
                        </Text>
                      )}
                    </label>
                  )}
                />

                <Controller
                  name="email"
                  control={form.control}
                  render={({ field, fieldState }) => (
                    <label>
                      <Text as="div" size="2" mb="2" weight="bold">
                        Email
                      </Text>
                      <TextField.Root
                        {...field}
                        placeholder="Enter the email"
                        invalid={!!fieldState.error}
                      />
                      {fieldState.error && (
                        <Text size="2" as="p" color="red" mt="2">
                          {fieldState.error.message}
                        </Text>
                      )}
                    </label>
                  )}
                />
              </Flex>
            </form>
          </Dialog.Body>

          <Dialog.Footer>
            <Dialog.Close>
              <Button>Cancel</Button>
            </Dialog.Close>
            <Button
              type="submit"
              form="edit-resource-form"
              color="purple"
              disabled={!form.formState.isDirty}
              loading={
                form.formState.isSubmitting || form.formState.isSubmitSuccessful
              }
            >
              Save changes
            </Button>
          </Dialog.Footer>
        </FormProvider>
      </Dialog.Content>
    </Dialog.Root>
  );
};

Variants

Dashboard

12 variants found

Dialog in Reset Organization Custom Attribute Mappingdashboard

Dialog in Connection Metadata Xmldashboard

size 2 dialog in Managed List Dialogdashboard

size=2

size 2 dialog in Edit Vault Object Dialogdashboard

size=2

size 5 dialog in Edit Directory Custom Attribute Mappings Dialogdashboard

size=5

size 5 dialog in Onboard Impersonation Dialogdashboard

size=5

size 2 dialog in Onboard Impersonation Dialogdashboard

color=graysize=2

size 3 dialog in Slack Integration Dialogdashboard

size=3

size 3 dialog in Add Billing Info Modaldashboard

size=3

size 1 dialog in Upgrade Account Dialogdashboard

size=1

size 1 dialog in Audit Log Delete Event Dialogdashboardstatic

<Dialog.Root open={open} onOpenChange={handleOpenChange}>
    <Dialog.Content size="1">
      <AuditLogDeleteEventDialogContent
        event={event}
        onFormSubmitSuccess={async () => {
          await Promise.all([onDelete?.(), waitMilliseconds(500)]);
          void handleOpenChange(false);
        }}
      />
    </Dialog.Content>
  </Dialog.Root>

size=1

size 4 dialog in Update Provider Dialogdashboard

size=4

Context

Dialog.Body

Prop	Type	Default	Required
`indicators`	`"none" \| "x" \| "y" \| "left" \| "right" \| "top" \| "bottom" \| "all"`	—	no

Also supports MarginProps: m, mb, ml, mr, mt, mx, my

Dialog.Content

Prop	Type	Default	Required
`align`	`"center" \| "start"`	—	no
`asChild`	`boolean`	—	no
`container`	`Element \| DocumentFragment \| null`	—	no
`height`	`Responsive<string>`	—	no
`maxHeight`	`Responsive<string>`	—	no
`maxWidth`	`Responsive<string>`	—	no
`minHeight`	`Responsive<string>`	—	no
`minWidth`	`Responsive<string>`	—	no
`size`	`"1" \| "2" \| "3" \| "4" \| "5" \| "6"`	`3`	no
`width`	`Responsive<string>`	—	no

Dialog.Description

Prop	Type	Default	Required
`align`	`Responsive<"center" \| "left" \| "right">`	—	no
`color`	`"ruby" \| "gray" \| "gold" \| "bronze" \| "brown" \| "yellow" \| "amber" \| "orange" \| "tomato" \| "red" \| "crimson" \| "pink" \| "plum" \| "purple" \| "violet" \| "iris" \| "indigo" \| "blue" \| ... 8 more ...`	—	no
`highContrast`	`boolean`	—	no
`size`	`Responsive<"1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \| "8" \| "9">`	—	no
`trim`	`Responsive<"end" \| "normal" \| "both" \| "start">`	—	no
`truncate`	`boolean`	—	no
`weight`	`Responsive<"bold" \| "medium" \| "light" \| "regular">`	—	no
`wrap`	`Responsive<"wrap" \| "nowrap" \| "pretty" \| "balance">`	—	no

Also supports MarginProps: m, mb, ml, mr, mt, mx, my

Dialog.Header

Prop	Type	Default	Required
`title`	`ReactNode`	—	yes
`description`	`ReactNode`	—	no
`error`	`ReactNode`	—	no

Also supports MarginProps: m, mb, ml, mr, mt, mx, my

Dialog.Title

Prop	Type	Default	Required
`align`	`Responsive<"center" \| "left" \| "right">`	—	no
`as`	`"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"`	—	no
`color`	`"ruby" \| "gray" \| "gold" \| "bronze" \| "brown" \| "yellow" \| "amber" \| "orange" \| "tomato" \| "red" \| "crimson" \| "pink" \| "plum" \| "purple" \| "violet" \| "iris" \| "indigo" \| "blue" \| ... 8 more ...`	—	no
`highContrast`	`boolean`	—	no
`size`	`Responsive<"1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \| "8" \| "9">`	—	no
`trim`	`Responsive<"end" \| "normal" \| "both" \| "start">`	—	no
`truncate`	`boolean`	—	no
`weight`	`Responsive<"bold" \| "medium" \| "light" \| "regular">`	—	no
`wrap`	`Responsive<"wrap" \| "nowrap" \| "pretty" \| "balance">`	—	no

Also supports MarginProps: m, mb, ml, mr, mt, mx, my

Usage

Used 563 times across 2 packages

Dashboard

475

Admin Portal

Variant Distribution

size

14%

54%

18%

11%

color

gray

100%

trim

both

100%

align

start

100%

Where it's used

109 files

packages/dashboard/src/components/connections/certificate-expiry-callout.tsx14

packages/dashboard/src/components/configuration/stripe-entitlements/dialogs/connected-dialog.tsx9

packages/dashboard/src/components/pipes/add-provider-dialog.tsx9

packages/dashboard/src/components/flags/slack-integration-dialog.tsx8

packages/dashboard/src/components/roles/edit-user-role-dialog.tsx8

packages/dashboard/src/legacy-pages/[environmentId]/organizations/[organizationId]/domains/add-domains-dialog/add-domains-dialog.tsx8

packages/dashboard/src/components/branding/logo-icon-fit-dialog.tsx7

/domains

packages/dashboard/src/app/(private)/(sidebar)/domains/verify-custom-email-domain-dialog-content.tsx8

/branding/edit

packages/dashboard/src/app/(private)/(chromeless)/branding/edit/edit-branding.tsx7

/:environmentId/applications/:applicationId

packages/dashboard/src/app/(private)/(sidebar)/[environmentId]/applications/[applicationId]/edit-application-dialog.tsx7

Show 99 more files

Dialog

Props

Dialog.Body

indicators

Dialog.Content

align

asChild

container

height

maxHeight

maxWidth

minHeight

minWidth

size

width

Dialog.Description

align

color

highContrast

size

trim

truncate

weight

wrap

Dialog.Header

title

description

error

Dialog.Title

align

as

color

highContrast

size

trim

truncate

weight

wrap

Usage

Sizes

With Inset

With scrollable content

With an error callout

With body scroll Deprecated

With tables

Using with forms

Error handling

Form patterns

Form structure and errors

Field-level validation

Recipes

Add resource dialog

Edit resource dialog

Variants

Dashboard

Context

Full API Reference

Full API Reference

Dialog.Body

Dialog.Content

Dialog.Description

Dialog.Header

Dialog.Title

Usage Statistics

Usage Statistics

Usage

Variant Distribution

Where it's used

`indicators`

`align`

`asChild`

`container`

`height`

`maxHeight`

`maxWidth`

`minHeight`

`minWidth`

`size`

`width`

`align`

`color`

`highContrast`

`size`

`trim`

`truncate`

`weight`

`wrap`

`title`

`description`

`error`

`align`

`as`

`color`

`highContrast`

`size`

`trim`

`truncate`

`weight`

`wrap`