Popover

Use Popover...

To show optional, additional information in context that might be useful for the user.
To give short definitions of terms or phrases, or to provide some extra context.

Don't use Popover...

To show critical information for a user to complete a task.
To capture information or display multiple actions. Use Modal Dialog instead.

Default

Popovers act in a similar way to tooltips, except that they show up on click rather than on hover. Refer to Popover vs tooltip for more details.

ReactVanilla

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover>
    <PopoverLauncher>
      <Button>Launch a Popover</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Default example">
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>
</FlexBox>

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover>
    <PopoverLauncher>
      <Button>Launch a Popover</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Default example">
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>
</FlexBox>

<div
  class="swan-display-flex"
  style="align-items: center; justify-content: center"
>
  <div class="swan-popover-container swan-m-11">
    <button
      type="button"
      class="swan-button swan-button-skin-secondary"
      data-popover-target="my-example-popover"
      data-popover-position="top"
    >
      Launch a Popover
    </button>
    <template class="swan-popover" data-popover="my-example-popover">
      Here is the content in the Popover.
    </template>
  </div>
</div>

<div
  class="swan-display-flex"
  style="align-items: center; justify-content: center"
>
  <div class="swan-popover-container swan-m-11">
    <button
      type="button"
      class="swan-button swan-button-skin-secondary"
      data-popover-target="my-example-popover"
      data-popover-position="top"
    >
      Launch a Popover
    </button>
    <template class="swan-popover" data-popover="my-example-popover">
      Here is the content in the Popover.
    </template>
  </div>
</div>

Trigger

Use the PopoverLauncher subcomponent to place a clickable trigger element—usually a Button or Link as a Button. When triggered, the Popover is attached to its trigger element.

ReactVanilla

<FlexBox
  flexDirection="column"
  gap={8}
  justifyContent="center"
  alignItems="center"
  my={11}
>
  <Popover>
    <PopoverLauncher>
      <Button>Launch popover with Button</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Example with button">
      This is the SWAN popover that you can use in your applications.
    </PopoverContent>
  </Popover>
  <Popover>
    <PopoverLauncher>
      <Link
        render={(p, ref) => (
          <Button ref={ref} skin="link" className={p.className} {...p} />
        )}
      >
        Launch popover with Link as Button
      </Link>
    </PopoverLauncher>
    <PopoverContent aria-label="Example with link">
      This is the SWAN popover that you can use in your applications.
    </PopoverContent>
  </Popover>
</FlexBox>

<FlexBox
  flexDirection="column"
  gap={8}
  justifyContent="center"
  alignItems="center"
  my={11}
>
  <Popover>
    <PopoverLauncher>
      <Button>Launch popover with Button</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Example with button">
      This is the SWAN popover that you can use in your applications.
    </PopoverContent>
  </Popover>
  <Popover>
    <PopoverLauncher>
      <Link
        render={(p, ref) => (
          <Button ref={ref} skin="link" className={p.className} {...p} />
        )}
      >
        Launch popover with Link as Button
      </Link>
    </PopoverLauncher>
    <PopoverContent aria-label="Example with link">
      This is the SWAN popover that you can use in your applications.
    </PopoverContent>
  </Popover>
</FlexBox>

<div
  class="swan-display-flex swan-my-11"
  style="align-items: center; flex-direction: column; justify-content: center; gap: var(--swan-sem-space-8);"
>
  <div class="swan-popover-container">
    <span class="swan-popover-launcher"
      ><button
        type="button"
        data-popover-target="my-example-popover"
        data-popover-position="top"
        class="swan-button swan-button-skin-secondary"
      >
        Launch popover with Button
      </button></span
    >
    <template class="swan-popover" data-popover="my-example-popover">
      This is the SWAN popover that you can use in your applications.
    </template>
  </div>
  <div class="swan-popover-container">
    <span class="swan-popover-launcher"
      ><button
        type="button"
        data-popover-target="my-example-popover"
        data-popover-position="top"
        class="swan-link swan-button-skin-link"
      >
        Launch popover with Link as Button
      </button></span
    >
    <template class="swan-popover" data-popover="my-example-popover2">
      This is the SWAN popover that you can use in your applications.
    </template>
  </div>
</div>

<div
  class="swan-display-flex swan-my-11"
  style="align-items: center; flex-direction: column; justify-content: center; gap: var(--swan-sem-space-8);"
>
  <div class="swan-popover-container">
    <span class="swan-popover-launcher"
      ><button
        type="button"
        data-popover-target="my-example-popover"
        data-popover-position="top"
        class="swan-button swan-button-skin-secondary"
      >
        Launch popover with Button
      </button></span
    >
    <template class="swan-popover" data-popover="my-example-popover">
      This is the SWAN popover that you can use in your applications.
    </template>
  </div>
  <div class="swan-popover-container">
    <span class="swan-popover-launcher"
      ><button
        type="button"
        data-popover-target="my-example-popover"
        data-popover-position="top"
        class="swan-link swan-button-skin-link"
      >
        Launch popover with Link as Button
      </button></span
    >
    <template class="swan-popover" data-popover="my-example-popover2">
      This is the SWAN popover that you can use in your applications.
    </template>
  </div>
</div>

Position

Popover will automatically position itself, trying to avoid its contents rendering off-screen, and it will typically have its arrowhead pointing to the center of the trigger element. With the position prop, you can specify its preferred orientation relative to the trigger element: Top, Bottom, Left, Right.

By default, the offset prop should be set to 8px. This is the space between the trigger element and the Popover.

() => {
  const [position, setPosition] = React.useState('top')
  return (
    <>
      <div>
        <Dropdown
          value={position}
          aria-label="dropdown-default"
          onChange={e => setPosition(e.target.value)}
        >
          <DropdownOption value="top">Top</DropdownOption>
          <DropdownOption value="bottom">Bottom</DropdownOption>
          <DropdownOption value="left">Left</DropdownOption>
          <DropdownOption value="right">Right</DropdownOption>
        </Dropdown>
      </div>
      <FlexBox alignItems="center" justifyContent="center" my="10">
        <Popover position={position}>
          <PopoverLauncher>
            <Button>Launch a Popover</Button>
          </PopoverLauncher>
          <PopoverContent aria-labelledby="popover-position-example-heading">
            <Typography
              fontSkin="title-item"
              id="popover-position-example-heading"
            >
              Hello
            </Typography>
            <Typography as="p">Some content inside a Typography tag</Typography>
            Here is some content inside a Popover
          </PopoverContent>
        </Popover>
      </FlexBox>
    </>
  )
}

() => {
  const [position, setPosition] = React.useState('top')
  return (
    <>
      <div>
        <Dropdown
          value={position}
          aria-label="dropdown-default"
          onChange={e => setPosition(e.target.value)}
        >
          <DropdownOption value="top">Top</DropdownOption>
          <DropdownOption value="bottom">Bottom</DropdownOption>
          <DropdownOption value="left">Left</DropdownOption>
          <DropdownOption value="right">Right</DropdownOption>
        </Dropdown>
      </div>
      <FlexBox alignItems="center" justifyContent="center" my="10">
        <Popover position={position}>
          <PopoverLauncher>
            <Button>Launch a Popover</Button>
          </PopoverLauncher>
          <PopoverContent aria-labelledby="popover-position-example-heading">
            <Typography
              fontSkin="title-item"
              id="popover-position-example-heading"
            >
              Hello
            </Typography>
            <Typography as="p">Some content inside a Typography tag</Typography>
            Here is some content inside a Popover
          </PopoverContent>
        </Popover>
      </FlexBox>
    </>
  )
}

Content

Popovers can contain any content. We recommend content that is short and directive, that is not critical for users to complete a task. Refer to Guidelines for more info. Popovers have a maximum width of 375px.

ReactVanilla

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover>
    <PopoverLauncher>
      <Button>Launch popover</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Content example">
      <FlexBox
        justifyContent="center"
        alignItems="center"
        flexDirection="row"
        gap="4"
      >
        <FluidImage src="https://picsum.photos/100" alt="random photo" />
        <P>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc congue
          laoreet convallis.
        </P>
      </FlexBox>
    </PopoverContent>
  </Popover>
</FlexBox>

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover>
    <PopoverLauncher>
      <Button>Launch popover</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Content example">
      <FlexBox
        justifyContent="center"
        alignItems="center"
        flexDirection="row"
        gap="4"
      >
        <FluidImage src="https://picsum.photos/100" alt="random photo" />
        <P>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc congue
          laoreet convallis.
        </P>
      </FlexBox>
    </PopoverContent>
  </Popover>
</FlexBox>

<div
  class="swan-display-flex swan-m-11"
  style="align-items: center; justify-content: center"
>
  <div class="swan-popover-container">
    <button
      type="button"
      class="swan-button swan-button-skin-secondary"
      data-popover-target="my-example-popover23"
      data-popover-position="top"
    >
      Launch popover
    </button>
    <template class="swan-popover" data-popover="my-example-popover23">
      <div
        class="swan-display-flex"
        style="align-items: center; flex-direction: row; justify-content: center; gap: var(--swan-sem-space-4);"
      >
        <img
          src="https://picsum.photos/100"
          alt="random photo"
          class="swan-fluid-image"
        />
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc congue
          laoreet convallis.
        </p>
      </div>
    </template>
  </div>
</div>

<div
  class="swan-display-flex swan-m-11"
  style="align-items: center; justify-content: center"
>
  <div class="swan-popover-container">
    <button
      type="button"
      class="swan-button swan-button-skin-secondary"
      data-popover-target="my-example-popover23"
      data-popover-position="top"
    >
      Launch popover
    </button>
    <template class="swan-popover" data-popover="my-example-popover23">
      <div
        class="swan-display-flex"
        style="align-items: center; flex-direction: row; justify-content: center; gap: var(--swan-sem-space-4);"
      >
        <img
          src="https://picsum.photos/100"
          alt="random photo"
          class="swan-fluid-image"
        />
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc congue
          laoreet convallis.
        </p>
      </div>
    </template>
  </div>
</div>

Full bleed

Use fullBleed to remove the padding around the Popover’s contents. Useful when placing an edge-to-edge image in a Popover.

ReactVanilla

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover>
    <PopoverLauncher>
      <Button>Launch a Popover</Button>
    </PopoverLauncher>
    <PopoverContent fullBleed aria-label="Full bleed example">
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>
</FlexBox>

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover>
    <PopoverLauncher>
      <Button>Launch a Popover</Button>
    </PopoverLauncher>
    <PopoverContent fullBleed aria-label="Full bleed example">
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>
</FlexBox>

<div
  class="swan-display-flex swan-m-11"
  style="align-items: center; justify-content: center"
>
  <div class="swan-popover-container">
    <button
      type="button"
      class="swan-button swan-button-skin-secondary"
      data-popover-target="my-example-popover"
      data-popover-position="top"
      data-popover-skin="full-bleed"
    >
      Launch a Popover
    </button>
    <template class="swan-popover" data-popover="my-example-popover">
      Here is the content in the Popover.
    </template>
  </div>
</div>

<div
  class="swan-display-flex swan-m-11"
  style="align-items: center; justify-content: center"
>
  <div class="swan-popover-container">
    <button
      type="button"
      class="swan-button swan-button-skin-secondary"
      data-popover-target="my-example-popover"
      data-popover-position="top"
      data-popover-skin="full-bleed"
    >
      Launch a Popover
    </button>
    <template class="swan-popover" data-popover="my-example-popover">
      Here is the content in the Popover.
    </template>
  </div>
</div>

With a close button

Use the PopoverCloser component with a Button to configure its click handlers to close the Popover. We recommend styling and positioning the close button as demonstrated above.

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover>
    <PopoverLauncher>
      <Button>Launch a Popover</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Close button example">
      <FlexBox justifyContent="space-between">
        <FlexBox alignItems="center">
          Here is the content in the Popover.
        </FlexBox>
        <FlexBox ml="between-icon-and-text">
          <PopoverCloser>
            <Button skin="tertiary" buttonShape="round">
              <Icon iconType="close" alt="Close" />
            </Button>
          </PopoverCloser>
        </FlexBox>
      </FlexBox>
    </PopoverContent>
  </Popover>
</FlexBox>

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover>
    <PopoverLauncher>
      <Button>Launch a Popover</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Close button example">
      <FlexBox justifyContent="space-between">
        <FlexBox alignItems="center">
          Here is the content in the Popover.
        </FlexBox>
        <FlexBox ml="between-icon-and-text">
          <PopoverCloser>
            <Button skin="tertiary" buttonShape="round">
              <Icon iconType="close" alt="Close" />
            </Button>
          </PopoverCloser>
        </FlexBox>
      </FlexBox>
    </PopoverContent>
  </Popover>
</FlexBox>

As a dialog

dialog is deprecated in SWAN v3.16

All popovers are now dialogs by default so this prop is no longer necessary.

Use dialog if the Popover contents contain interactive elements.

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover position="bottom">
    <PopoverLauncher>
      <Button>Popover Launcher</Button>
    </PopoverLauncher>
    <PopoverContent dialog aria-label="Dialog example (deprecated)">
      <PopoverCloser textAlign="right">
        <Button skin="unstyled">
          <Icon iconType="close" />
        </Button>
      </PopoverCloser>
      <Typography marginBottom={2}>
        Here is some content inside a popover
      </Typography>
      <Button
        marginBottom={2}
        onClick={() => {
          alert('You clicked me!')
        }}
      >
        Click me!
      </Button>
    </PopoverContent>
  </Popover>
</FlexBox>

<FlexBox justifyContent="center" alignItems="center" my={11}>
  <Popover position="bottom">
    <PopoverLauncher>
      <Button>Popover Launcher</Button>
    </PopoverLauncher>
    <PopoverContent dialog aria-label="Dialog example (deprecated)">
      <PopoverCloser textAlign="right">
        <Button skin="unstyled">
          <Icon iconType="close" />
        </Button>
      </PopoverCloser>
      <Typography marginBottom={2}>
        Here is some content inside a popover
      </Typography>
      <Button
        marginBottom={2}
        onClick={() => {
          alert('You clicked me!')
        }}
      >
        Click me!
      </Button>
    </PopoverContent>
  </Popover>
</FlexBox>

Control

At times, you might want to control the popover state programmatically, i.e., without the user actually clicking the popover button. This can be achieved by using React's ref to trigger the button click. Below's the sample:

() => {
  const ref = React.useRef(null)
  React.useEffect(() => {
    setTimeout(() => {
      // simulating click
      ref.current.click()
    }, 1000)
  }, [])
  return (
    <FlexBox justifyContent="center" alignItems="center" my={5}>
      <Popover>
        <PopoverLauncher>
          <Button ref={ref}>Launch a Popover</Button>
        </PopoverLauncher>
        <PopoverContent aria-label="Controlled example">
          Popover launched programatically.
        </PopoverContent>
      </Popover>
    </FlexBox>
  )
}

() => {
  const ref = React.useRef(null)
  React.useEffect(() => {
    setTimeout(() => {
      // simulating click
      ref.current.click()
    }, 1000)
  }, [])
  return (
    <FlexBox justifyContent="center" alignItems="center" my={5}>
      <Popover>
        <PopoverLauncher>
          <Button ref={ref}>Launch a Popover</Button>
        </PopoverLauncher>
        <PopoverContent aria-label="Controlled example">
          Popover launched programatically.
        </PopoverContent>
      </Popover>
    </FlexBox>
  )
}

Accessibility

The PopoverContent component needs an accessible name that briefly describes its purpose or function. The name will be applied to its underlying dialog element and used by assistive technologies to describe it to its users.

If visible text already exists that summarizes its purpose, the PopoverContent element should have an aria-labelledby attribute whose value is the id of the element containing that text. Examples include a heading inside the PopoverContent, the text in the PopoverLauncher, or nearby text on the page.

If no visible text exists that summarizes its purpose, the PopoverContent element should have an aria-label attribute whose value acts as the name for the dialog. Ensure the aria-label text is localized since it will be read to the user.

<FlexBox
  flexDirection="column"
  justifyContent="center"
  alignItems="center"
  gap={4}
>
  {/* Example using a heading as the accessible name */}
  <Popover>
    <PopoverLauncher>
      <Button skin="unstyled">
        <Icon iconType="info" />
        <VisuallyHidden>Check out this example</VisuallyHidden>
      </Button>
    </PopoverLauncher>
    <PopoverContent aria-labelledby="example-1-popover-name">
      <H3 fontSkin="body-standard-bold" id="example-1-popover-name">
        Example 1
      </H3>
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>

  {/* Example using nearby text as the accessible name */}
  <FlexBox justifyContent="center" alignItems="center" gap={4}>
    <Span id="example-2-popover-name">Example 2</Span>
    <Popover>
      <PopoverLauncher>
        <Button skin="unstyled">
          <Icon iconType="info" />
          <Span visuallyHidden>Example 2</Span>
        </Button>
      </PopoverLauncher>
      <PopoverContent aria-labelledby="example-2-popover-name">
        Here is the content in the Popover.
      </PopoverContent>
    </Popover>
  </FlexBox>

  {/* Example using the launcher text as the accessible name */}
  <Popover>
    <PopoverLauncher>
      <Button>
        <Span id="example-3-popover-name">Example 3</Span>
      </Button>
    </PopoverLauncher>
    <PopoverContent aria-labelledby="example-3-popover-name">
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>

  {/* Example using a custom label as the accessible name */}
  <Popover>
    <PopoverLauncher>
      <Button>Example 4</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Example 4">
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>
</FlexBox>

<FlexBox
  flexDirection="column"
  justifyContent="center"
  alignItems="center"
  gap={4}
>
  {/* Example using a heading as the accessible name */}
  <Popover>
    <PopoverLauncher>
      <Button skin="unstyled">
        <Icon iconType="info" />
        <VisuallyHidden>Check out this example</VisuallyHidden>
      </Button>
    </PopoverLauncher>
    <PopoverContent aria-labelledby="example-1-popover-name">
      <H3 fontSkin="body-standard-bold" id="example-1-popover-name">
        Example 1
      </H3>
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>

  {/* Example using nearby text as the accessible name */}
  <FlexBox justifyContent="center" alignItems="center" gap={4}>
    <Span id="example-2-popover-name">Example 2</Span>
    <Popover>
      <PopoverLauncher>
        <Button skin="unstyled">
          <Icon iconType="info" />
          <Span visuallyHidden>Example 2</Span>
        </Button>
      </PopoverLauncher>
      <PopoverContent aria-labelledby="example-2-popover-name">
        Here is the content in the Popover.
      </PopoverContent>
    </Popover>
  </FlexBox>

  {/* Example using the launcher text as the accessible name */}
  <Popover>
    <PopoverLauncher>
      <Button>
        <Span id="example-3-popover-name">Example 3</Span>
      </Button>
    </PopoverLauncher>
    <PopoverContent aria-labelledby="example-3-popover-name">
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>

  {/* Example using a custom label as the accessible name */}
  <Popover>
    <PopoverLauncher>
      <Button>Example 4</Button>
    </PopoverLauncher>
    <PopoverContent aria-label="Example 4">
      Here is the content in the Popover.
    </PopoverContent>
  </Popover>
</FlexBox>

Props

Popover

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.