DialogTrigger

DialogTrigger serves as a wrapper around a Dialog and its associated trigger, linking the Dialog's open state with the trigger's press state. Additionally, it allows you to customize the type and positioning of the Dialog.

install	`yarn add @react-spectrum/dialog`
version	3.3.4
usage	`import {DialogTrigger, Dialog} from '@react-spectrum/dialog'`

View repository

GitHub

View package

NPM

Example#

<DialogTrigger type="popover">
  <ActionButton>Disk Status</ActionButton>
  <Dialog>
    <Heading>C://</Heading>
    <Divider />
    <Content>
      <Text>
        50% disk space remaining.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<DialogTrigger type="popover">
  <ActionButton>Disk Status</ActionButton>
  <Dialog>
    <Heading>C://</Heading>
    <Divider />
    <Content>
      <Text>
        50% disk space remaining.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger type="popover">
    <ActionButton>
      Disk Status
    </ActionButton>
    <Dialog>
      <Heading>
        C://
      </Heading>
      <Divider />
      <Content>
        <Text>
          50% disk space
          remaining.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Content#

The DialogTrigger accepts exactly two children: the element which triggers opening of the Dialog and the Dialog itself. The trigger must be the first child passed into the DialogTrigger and should be an element that supports press events.

If your Dialog has buttons within it that should close the Dialog when pressed, you must wrap the Dialog in a function in order to propagate the DialogTrigger's close function to the Dialog's children. Dialogs that do not contain such interactive elements can simply provide the Dialog component as is to the DialogTrigger as its second child.

The example below demonstrates how to pass the DialogTrigger's close function to the Dialog's buttons.

<DialogTrigger>
  <ActionButton>Checkout</ActionButton>
  {(close) => (
    <Dialog>
      <Heading>Confirm checkout?</Heading>
      <Divider />
      <Content>
        <Text>
          You have 5 items in your cart. Proceed to checkout?
        </Text>
      </Content>
      <ButtonGroup>
        <Button variant="secondary" onPress={close}>Cancel</Button>
        <Button variant="cta" onPress={close} autoFocus>Confirm</Button>
      </ButtonGroup>
    </Dialog>
  )}
</DialogTrigger>

<WRAPPER>
  <DialogTrigger>
    <ActionButton>Checkout</ActionButton>
    {(close) => (
      <Dialog>
        <Heading>Confirm checkout?</Heading>
        <Divider />
        <Content>
          <Text>
            You have 5 items in your cart. Proceed to
            checkout?
          </Text>
        </Content>
        <ButtonGroup>
          <Button variant="secondary" onPress={close}>
            Cancel
          </Button>
          <Button variant="cta" onPress={close} autoFocus>
            Confirm
          </Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger>
    <ActionButton>
      Checkout
    </ActionButton>
    {(close) => (
      <Dialog>
        <Heading>
          Confirm
          checkout?
        </Heading>
        <Divider />
        <Content>
          <Text>
            You have 5
            items in your
            cart. Proceed
            to checkout?
          </Text>
        </Content>
        <ButtonGroup>
          <Button
            variant="secondary"
            onPress={close}
          >
            Cancel
          </Button>
          <Button
            variant="cta"
            onPress={close}
            autoFocus
          >
            Confirm
          </Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

Dialog types#

By providing a type prop, you can specify the type of Dialog that is rendered by your DialogTrigger. Note that pressing the Esc key will close the Dialog regardless of its type.

Modal Dialogs create an underlay that blocks access to the underlying user interface until the Dialog is closed. Sizing options can be found on the Dialog page. Focus is trapped inside the Modal as per the accessibility guidelines laid out by W3C.

<WRAPPER>
  <DialogTrigger type="modal">
    <ActionButton>Unlink</ActionButton>
    {(close) => (
      <Dialog>
        <Heading>Unlinking email</Heading>
        <Divider />
        <Content>
          <Text>
            This will unlink your email from your profile "TestUser". Are you
            sure?
          </Text>
        </Content>
        <ButtonGroup>
          <Button variant="secondary" onPress={close}>Cancel</Button>
          <Button variant="cta" onPress={close} autoFocus>Confirm</Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger type="modal">
    <ActionButton>Unlink</ActionButton>
    {(close) => (
      <Dialog>
        <Heading>Unlinking email</Heading>
        <Divider />
        <Content>
          <Text>
            This will unlink your email from your profile
            "TestUser". Are you sure?
          </Text>
        </Content>
        <ButtonGroup>
          <Button variant="secondary" onPress={close}>
            Cancel
          </Button>
          <Button variant="cta" onPress={close} autoFocus>
            Confirm
          </Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger type="modal">
    <ActionButton>
      Unlink
    </ActionButton>
    {(close) => (
      <Dialog>
        <Heading>
          Unlinking email
        </Heading>
        <Divider />
        <Content>
          <Text>
            This will
            unlink your
            email from
            your profile
            "TestUser".
            Are you sure?
          </Text>
        </Content>
        <ButtonGroup>
          <Button
            variant="secondary"
            onPress={close}
          >
            Cancel
          </Button>
          <Button
            variant="cta"
            onPress={close}
            autoFocus
          >
            Confirm
          </Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

If a Dialog without an underlay is needed, consider using a Popover Dialog. See Dialog placement for how you can customize the positioning. Note that popovers are automatically rendered as modals on mobile by default. See the mobile type option for more information.

<DialogTrigger type="popover">
  <ActionButton>Info</ActionButton>
  <Dialog>
    <Heading>Version Info</Heading>
    <Divider />
    <Content>
      <Text>
        Version 1.0.0, Copyright 2020
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<DialogTrigger type="popover">
  <ActionButton>Info</ActionButton>
  <Dialog>
    <Heading>Version Info</Heading>
    <Divider />
    <Content>
      <Text>
        Version 1.0.0, Copyright 2020
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger type="popover">
    <ActionButton>
      Info
    </ActionButton>
    <Dialog>
      <Heading>
        Version Info
      </Heading>
      <Divider />
      <Content>
        <Text>
          Version 1.0.0,
          Copyright 2020
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Tray#

Tray Dialogs are typically used to portray information on mobile devices or smaller screens.

<DialogTrigger type="tray">
  <ActionButton>Check Messages</ActionButton>
  <Dialog>
    <Heading>New Messages</Heading>
    <Divider />
    <Content>
      <Text>
        You have 5 new messages.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<DialogTrigger type="tray">
  <ActionButton>Check Messages</ActionButton>
  <Dialog>
    <Heading>New Messages</Heading>
    <Divider />
    <Content>
      <Text>
        You have 5 new messages.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger type="tray">
    <ActionButton>
      Check Messages
    </ActionButton>
    <Dialog>
      <Heading>
        New Messages
      </Heading>
      <Divider />
      <Content>
        <Text>
          You have 5 new
          messages.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Fullscreen#

Fullscreen Dialogs are a fullscreen variant of the Modal Dialog, only revealing a small portion of the page behind the underlay. Use this variant for more complex workflows that do not fit in the available Modal Dialog sizes. This variant does not support isDismissible.

<WRAPPER>
  <DialogTrigger type="fullscreen">
    <ActionButton>See Details</ActionButton>
    {(close) => (
      <Dialog>
        <Heading>Package details</Heading>
        <Divider />
        <Content>
          <Text>
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sit
            amet tristique risus. In sit amet suscipit lorem. Orci varius
            natoque penatibus et magnis dis parturient montes, nascetur
            ridiculus mus. In condimentum imperdiet metus non condimentum. Duis
            eu velit et quam accumsan tempus at id velit. Duis elementum
            elementum purus, id tempus mauris posuere a. Nunc vestibulum sapien
            pellentesque lectus commodo ornare.
          </Text>
        </Content>
        <ButtonGroup>
          <Button variant="secondary" onPress={close}>Cancel</Button>
          <Button variant="cta" onPress={close} autoFocus>Buy</Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger type="fullscreen">
    <ActionButton>See Details</ActionButton>
    {(close) => (
      <Dialog>
        <Heading>Package details</Heading>
        <Divider />
        <Content>
          <Text>
            Lorem ipsum dolor sit amet, consectetur
            adipiscing elit. Proin sit amet tristique risus.
            In sit amet suscipit lorem. Orci varius natoque
            penatibus et magnis dis parturient montes,
            nascetur ridiculus mus. In condimentum imperdiet
            metus non condimentum. Duis eu velit et quam
            accumsan tempus at id velit. Duis elementum
            elementum purus, id tempus mauris posuere a.
            Nunc vestibulum sapien pellentesque lectus
            commodo ornare.
          </Text>
        </Content>
        <ButtonGroup>
          <Button variant="secondary" onPress={close}>Cancel
          </Button>
          <Button variant="cta" onPress={close} autoFocus>
            Buy
          </Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger type="fullscreen">
    <ActionButton>
      See Details
    </ActionButton>
    {(close) => (
      <Dialog>
        <Heading>
          Package details
        </Heading>
        <Divider />
        <Content>
          <Text>
            Lorem ipsum
            dolor sit
            amet,
            consectetur
            adipiscing
            elit. Proin
            sit amet
            tristique
            risus. In sit
            amet suscipit
            lorem. Orci
            varius
            natoque
            penatibus et
            magnis dis
            parturient
            montes,
            nascetur
            ridiculus
            mus. In
            condimentum
            imperdiet
            metus non
            condimentum.
            Duis eu velit
            et quam
            accumsan
            tempus at id
            velit. Duis
            elementum
            elementum
            purus, id
            tempus mauris
            posuere a.
            Nunc
            vestibulum
            sapien
            pellentesque
            lectus
            commodo
            ornare.
          </Text>
        </Content>
        <ButtonGroup>
          <Button
            variant="secondary"
            onPress={close}
          >
            Cancel
          </Button>
          <Button
            variant="cta"
            onPress={close}
            autoFocus
          >
            Buy
          </Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

Fullscreen takeover#

Fullscreen takeover Dialogs are similar to the fullscreen variant except that the Dialog covers the entire screen.

<DialogTrigger type="fullscreenTakeover">
  <ActionButton>Register</ActionButton>
  {(close) => (
    <Dialog>
      <Heading>Register a new account</Heading>
      <Divider />
      <Content>
        <Form>
          <TextField label="Name" />
          <TextField label="Email address" />
          <Checkbox>Make profile private</Checkbox>
        </Form>
      </Content>
      <ButtonGroup>
        <Button variant="secondary" onPress={close}>Cancel</Button>
        <Button variant="cta" onPress={close} autoFocus>Confirm</Button>
      </ButtonGroup>
    </Dialog>
  )}
</DialogTrigger>

<WRAPPER>
  <DialogTrigger type="fullscreenTakeover">
    <ActionButton>Register</ActionButton>
    {(close) => (
      <Dialog>
        <Heading>Register a new account</Heading>
        <Divider />
        <Content>
          <Form>
            <TextField label="Name" />
            <TextField label="Email address" />
            <Checkbox>Make profile private</Checkbox>
          </Form>
        </Content>
        <ButtonGroup>
          <Button variant="secondary" onPress={close}>
            Cancel
          </Button>
          <Button variant="cta" onPress={close} autoFocus>
            Confirm
          </Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger type="fullscreenTakeover">
    <ActionButton>
      Register
    </ActionButton>
    {(close) => (
      <Dialog>
        <Heading>
          Register a new
          account
        </Heading>
        <Divider />
        <Content>
          <Form>
            <TextField label="Name" />
            <TextField label="Email address" />
            <Checkbox>
              Make
              profile
              private
            </Checkbox>
          </Form>
        </Content>
        <ButtonGroup>
          <Button
            variant="secondary"
            onPress={close}
          >
            Cancel
          </Button>
          <Button
            variant="cta"
            onPress={close}
            autoFocus
          >
            Confirm
          </Button>
        </ButtonGroup>
      </Dialog>
    )}
  </DialogTrigger>
</WRAPPER>;

Dismissable#

If your Modal Dialog doesn't require the user to make a confirmation, you can set isDismissable on the DialogTrigger. This adds a close button that the user can press to dismiss the Dialog.

<DialogTrigger isDismissable type="modal">
  <ActionButton>User Status</ActionButton>
  <Dialog>
    <Heading>Status: Bob</Heading>
    <Divider />
    <Content>
      <Text>
        Last Login: December 12, 1989
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<DialogTrigger isDismissable type="modal">
  <ActionButton>User Status</ActionButton>
  <Dialog>
    <Heading>Status: Bob</Heading>
    <Divider />
    <Content>
      <Text>
        Last Login: December 12, 1989
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger
    isDismissable
    type="modal"
  >
    <ActionButton>
      User Status
    </ActionButton>
    <Dialog>
      <Heading>
        Status: Bob
      </Heading>
      <Divider />
      <Content>
        <Text>
          Last Login:
          December 12,
          1989
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Mobile type#

The mobileType prop allows you to specify what kind of Dialog should be displayed when viewed on mobile devices or smaller viewports. Note that on mobile, Popovers are not supported and will display as modals by default.

The example below renders as a Popover on desktop but switches to a Tray on mobile.

<DialogTrigger type="popover" mobileType="tray">
  <ActionButton>Info</ActionButton>
  <Dialog>
    <Heading>Version Info</Heading>
    <Divider />
    <Content>
      <Text>
        Version 1.0.0, Copyright 2020
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<DialogTrigger type="popover" mobileType="tray">
  <ActionButton>Info</ActionButton>
  <Dialog>
    <Heading>Version Info</Heading>
    <Divider />
    <Content>
      <Text>
        Version 1.0.0, Copyright 2020
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger
    type="popover"
    mobileType="tray"
  >
    <ActionButton>
      Info
    </ActionButton>
    <Dialog>
      <Heading>
        Version Info
      </Heading>
      <Divider />
      <Content>
        <Text>
          Version 1.0.0,
          Copyright 2020
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Dialog placement#

Popover Dialogs support a variety of placement options since they do not take over the user interface like Modal or Tray Dialogs.

Dialog anchor#

By default, popovers anchor themselves to their associated trigger. This can be overridden by providing a separate ref to the targetRef prop.

function Example() {
  let ref = React.useRef()

  return (
    <Flex gap="size-1000">
      <DialogTrigger type="popover" targetRef={ref}>
        <ActionButton>Trigger</ActionButton>
        <Dialog>
          <Heading>The Heading</Heading>
          <Divider />
          <Content>
            <Text>
              This is a popover anchored to the span.
            </Text>
          </Content>
        </Dialog>
      </DialogTrigger>
      <span
        ref={ref}
        style={{width: '100px'}}>
        Popover appears over here
      </span>
    </Flex>
  );
}

function Example() {
  let ref = React.useRef()

  return (
    <Flex gap="size-1000">
      <DialogTrigger type="popover" targetRef={ref}>
        <ActionButton>Trigger</ActionButton>
        <Dialog>
          <Heading>The Heading</Heading>
          <Divider />
          <Content>
            <Text>
              This is a popover anchored to the span.
            </Text>
          </Content>
        </Dialog>
      </DialogTrigger>
      <span
        ref={ref}
        style={{width: '100px'}}>
        Popover appears over here
      </span>
    </Flex>
  );
}

function Example() {
  let ref = React
    .useRef();

  return (
    <Flex gap="size-1000">
      <DialogTrigger
        type="popover"
        targetRef={ref}
      >
        <ActionButton>
          Trigger
        </ActionButton>
        <Dialog>
          <Heading>
            The Heading
          </Heading>
          <Divider />
          <Content>
            <Text>
              This is a
              popover
              anchored to
              the span.
            </Text>
          </Content>
        </Dialog>
      </DialogTrigger>
      <span
        ref={ref}
        style={{
          width: '100px'
        }}
      >
        Popover appears
        over here
      </span>
    </Flex>
  );
}

Placement#

The popover's placement with respect to its anchor element can be adjusted using the placement prop. See the props table below for a full list of available placement combinations.

<DialogTrigger type="popover" placement="right top">
  <ActionButton>Trigger</ActionButton>
  <Dialog>
    <Heading>The Heading</Heading>
    <Divider />
    <Content>
      <Text>
        This is a popover placed to the right of its
        trigger and offset so the arrow is at the top of the dialog.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger type="popover" placement="right top">
    <ActionButton>Trigger</ActionButton>
    <Dialog>
      <Heading>The Heading</Heading>
      <Divider />
      <Content>
        <Text>
          This is a popover placed to the right of its
          trigger and offset so the arrow is at the top of
          the dialog.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger
    type="popover"
    placement="right top"
  >
    <ActionButton>
      Trigger
    </ActionButton>
    <Dialog>
      <Heading>
        The Heading
      </Heading>
      <Divider />
      <Content>
        <Text>
          This is a
          popover placed
          to the right of
          its trigger and
          offset so the
          arrow is at the
          top of the
          dialog.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Offset and cross offset#

The Popover Dialog's offset with respect to its anchor element can be adjusted using the offset and crossOffset props. The offset prop controls the spacing applied along the main axis between the element and its anchor element whereas the crossOffset prop handles the spacing applied along the cross axis.

Below is a popover offset by an additional 50px above the trigger.

<DialogTrigger type="popover" placement="top" offset={50}>
  <ActionButton>Trigger</ActionButton>
  <Dialog>
    <Heading>Offset</Heading>
    <Divider />
    <Content>
      <Text>
        Offset by an additional 50px.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<DialogTrigger type="popover" placement="top" offset={50}>
  <ActionButton>Trigger</ActionButton>
  <Dialog>
    <Heading>Offset</Heading>
    <Divider />
    <Content>
      <Text>
        Offset by an additional 50px.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger
    type="popover"
    placement="top"
    offset={50}
  >
    <ActionButton>
      Trigger
    </ActionButton>
    <Dialog>
      <Heading>
        Offset
      </Heading>
      <Divider />
      <Content>
        <Text>
          Offset by an
          additional
          50px.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Below is a popover cross offset by an additional 100px to the right of the trigger.

<DialogTrigger type="popover" placement="top" crossOffset={100}>
  <ActionButton>Trigger</ActionButton>
  <Dialog>
    <Heading>Cross offset</Heading>
    <Divider />
    <Content>
      <Text>
        Offset by an additional 100px.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger
    type="popover"
    placement="top"
    crossOffset={100}
  >
    <ActionButton>Trigger</ActionButton>
    <Dialog>
      <Heading>Cross offset</Heading>
      <Divider />
      <Content>
        <Text>
          Offset by an additional 100px.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger
    type="popover"
    placement="top"
    crossOffset={100}
  >
    <ActionButton>
      Trigger
    </ActionButton>
    <Dialog>
      <Heading>
        Cross offset
      </Heading>
      <Divider />
      <Content>
        <Text>
          Offset by an
          additional
          100px.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Flipping#

By default, DialogTrigger attempts to flip popovers on the main axis in situations where the original placement would cause it to render out of view. This can be overridden by setting shouldFlip={false}. To see the difference between the two options, scroll this page so that the example below is near the bottom of the window.

<WRAPPER>
  <Flex gap="size-100" wrap>
    <DialogTrigger type="popover" placement="bottom">
      <ActionButton>Default DialogTrigger</ActionButton>
      <Dialog>
        <Heading>The Heading</Heading>
        <Divider />
        <Content>
          <Text>
            This is a popover that will flip if it can't fully render below the
            button.
          </Text>
        </Content>
      </Dialog>
    </DialogTrigger>

    <DialogTrigger type="popover" placement="bottom" shouldFlip={false}>
      <ActionButton>DialogTrigger with shouldFlip=false</ActionButton>
      <Dialog>
        <Heading>The Heading</Heading>
        <Divider />
        <Content>
          <Text>
            This is a popover that won't flip if it can't fully render below the
            button.
          </Text>
        </Content>
      </Dialog>
    </DialogTrigger>
  </Flex>
</WRAPPER>;

<WRAPPER>
  <Flex gap="size-100" wrap>
    <DialogTrigger type="popover" placement="bottom">
      <ActionButton>Default DialogTrigger</ActionButton>
      <Dialog>
        <Heading>The Heading</Heading>
        <Divider />
        <Content>
          <Text>
            This is a popover that will flip if it can't
            fully render below the button.
          </Text>
        </Content>
      </Dialog>
    </DialogTrigger>

    <DialogTrigger
      type="popover"
      placement="bottom"
      shouldFlip={false}
    >
      <ActionButton>
        DialogTrigger with shouldFlip=false
      </ActionButton>
      <Dialog>
        <Heading>The Heading</Heading>
        <Divider />
        <Content>
          <Text>
            This is a popover that won't flip if it can't
            fully render below the button.
          </Text>
        </Content>
      </Dialog>
    </DialogTrigger>
  </Flex>
</WRAPPER>;

<WRAPPER>
  <Flex
    gap="size-100"
    wrap
  >
    <DialogTrigger
      type="popover"
      placement="bottom"
    >
      <ActionButton>
        Default
        DialogTrigger
      </ActionButton>
      <Dialog>
        <Heading>
          The Heading
        </Heading>
        <Divider />
        <Content>
          <Text>
            This is a
            popover that
            will flip if
            it can't
            fully render
            below the
            button.
          </Text>
        </Content>
      </Dialog>
    </DialogTrigger>

    <DialogTrigger
      type="popover"
      placement="bottom"
      shouldFlip={false}
    >
      <ActionButton>
        DialogTrigger
        with
        shouldFlip=false
      </ActionButton>
      <Dialog>
        <Heading>
          The Heading
        </Heading>
        <Divider />
        <Content>
          <Text>
            This is a
            popover that
            won't flip if
            it can't
            fully render
            below the
            button.
          </Text>
        </Content>
      </Dialog>
    </DialogTrigger>
  </Flex>
</WRAPPER>;

Container padding#

You can control the minimum padding required between the Popover Dialog and the surrounding container via the containerPadding prop. This affects the positioning breakpoints that determine when the Dialog will attempt to flip.

The example below will flip the Dialog from above the trigger button to below the trigger button if the Dialog cannot render fully while maintaining 50px of padding between itself and the top of the browser.

<DialogTrigger type="popover" placement="top" containerPadding={50}>
  <ActionButton>Trigger</ActionButton>
  <Dialog>
    <Heading>The Heading</Heading>
    <Divider />
    <Content>
      <Text>
        This is a popover.
      </Text>
    </Content>
  </Dialog>
</DialogTrigger>

<WRAPPER>
  <DialogTrigger
    type="popover"
    placement="top"
    containerPadding={50}
  >
    <ActionButton>Trigger</ActionButton>
    <Dialog>
      <Heading>The Heading</Heading>
      <Divider />
      <Content>
        <Text>
          This is a popover.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

<WRAPPER>
  <DialogTrigger
    type="popover"
    placement="top"
    containerPadding={50}
  >
    <ActionButton>
      Trigger
    </ActionButton>
    <Dialog>
      <Heading>
        The Heading
      </Heading>
      <Divider />
      <Content>
        <Text>
          This is a
          popover.
        </Text>
      </Content>
    </Dialog>
  </DialogTrigger>
</WRAPPER>;

Events#

DialogTrigger accepts an onOpenChange handler which is triggered whenever the Dialog is opened or closed.

The example below uses onOpenChange to update a separate element with the current open state of the Dialog.

function Example() {
  let [state, setState] = React.useState(false);

  return (
    <Flex alignItems="center" gap="size-100">
      <DialogTrigger
        type="popover"
        placement="top"
        onOpenChange={(isOpen) => setState(isOpen)}
      >
        <ActionButton>Whispers</ActionButton>
        <Dialog>
          <Heading>Whispers and DMs</Heading>
          <Divider />
          <Content>
            <Text>
              You have 0 new messages.
            </Text>
          </Content>
        </Dialog>
      </DialogTrigger>
      <Text>Current open state: {state.toString()}</Text>
    </Flex>
  );
}

function Example() {
  let [state, setState] = React.useState(false);

  return (
    <Flex alignItems="center" gap="size-100">
      <DialogTrigger
        type="popover"
        placement="top"
        onOpenChange={(isOpen) => setState(isOpen)}
      >
        <ActionButton>Whispers</ActionButton>
        <Dialog>
          <Heading>Whispers and DMs</Heading>
          <Divider />
          <Content>
            <Text>
              You have 0 new messages.
            </Text>
          </Content>
        </Dialog>
      </DialogTrigger>
      <Text>Current open state: {state.toString()}</Text>
    </Flex>
  );
}

function Example() {
  let [state, setState] =
    React.useState(
      false
    );

  return (
    <Flex
      alignItems="center"
      gap="size-100"
    >
      <DialogTrigger
        type="popover"
        placement="top"
        onOpenChange={(
          isOpen
        ) =>
          setState(
            isOpen
          )}
      >
        <ActionButton>
        Whispers
        </ActionButton>
        <Dialog>
          <Heading>
          Whispers and
          DMs</Heading>
          <Divider />
          <Content>
            <Text>
              You have 0
              new
              messages.
            </Text>
          </Content>
        </Dialog>
      </DialogTrigger>
      <Text>
        Current open
        state:{' '}
        {state
          .toString()}
      </Text>
    </Flex>
  );
}

Props#

Name	Type	Default	Description
`children`	`[ ReactElement, SpectrumDialogClose \| ReactElement ]`	—	The Dialog and its trigger element. See the DialogTrigger Content section for more information on what to provide as children.
`type`	`'modal' \| 'popover' \| 'tray' \| 'fullscreen' \| 'fullscreenTakeover'`	`'modal'`	The type of Dialog that should be rendered. See the DialogTrigger types section for an explanation on each.
`mobileType`	`'modal' \| 'tray' \| 'fullscreen' \| 'fullscreenTakeover'`	—	The type of Dialog that should be rendered when on a mobile device. See DialogTrigger types section for an explanation on each.
`hideArrow`	`boolean`	—	Whether a popover type Dialog's arrow should be hidden.
`targetRef`	`RefObject<HTMLElement>`	—	The ref of the element the Dialog should visually attach itself to. Defaults to the trigger button if not defined.
`isDismissable`	`boolean`	—	Whether a modal type Dialog should be dismissable.
`isKeyboardDismissDisabled`	`boolean`	—	Whether pressing the escape key to close the dialog should be disabled.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`placement`	`Placement`	`'bottom'`	The placement of the element with respect to its anchor element.
`containerPadding`	`number`	`12`	The placement padding that should be applied between the element and its surrounding container.
`offset`	`number`	`0`	The additional offset applied along the main axis between the element and its anchor element.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`shouldFlip`	`boolean`	`true`	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.

Events

Name	Type	Default	Description
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.