Popover

A container that pops up from another element over other content. Triggered via click to give short, additional information in-context.

styleKeys: popoverscriptKeys: popover

UsageGuidelinesAPI

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>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>Here is the content in the Popover.</PopoverContent>
  </Popover>
</FlexBox>

<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>
</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>
</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>
      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>
      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>
      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>
      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-7);"
>
  <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-7);"
>
  <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>
            <Typography fontSkin="title-item">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>
            <Typography fontSkin="title-item">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. If Popover contents contain interactive elements, use the dialog prop (Refer to Popover as a dialog). Popovers have a maximum width of 375px.

ReactVanilla

<Popover>
  <PopoverLauncher>
    <Button>Launch popover</Button>
  </PopoverLauncher>
  <PopoverContent>
    <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>

<Popover>
  <PopoverLauncher>
    <Button>Launch popover</Button>
  </PopoverLauncher>
  <PopoverContent>
    <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>

<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-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>

<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-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>

Full bleed

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

<Popover my={11}>
  <PopoverLauncher>
    <Button>Launch a Popover</Button>
  </PopoverLauncher>
  <PopoverContent fullBleed>Here is the content in the Popover.</PopoverContent>
</Popover>

<Popover my={11}>
  <PopoverLauncher>
    <Button>Launch a Popover</Button>
  </PopoverLauncher>
  <PopoverContent fullBleed>Here is the content in the Popover.</PopoverContent>
</Popover>

As a dialog

Use dialog if the Popover contents contain interactive elements. A dialog Popover must contain a PopoverCloser element; SWAN doesn’t dictate what this element should look like. You may consider using a close icon as a button.

Ensure dialog Popovers have an accessible label. If the Popover has a heading: the PopoverContent element should have an attribute aria-labelledby whose value is the id of the heading. If the Popover does not have a heading: the PopoverContent element needs an aria-label attribute whose value acts as a title for the dialog. Ensure aria-label text is localized, since some browsers will read it to the user.

<Popover position="bottom" my="11">
  <PopoverLauncher>
    <Button>Popover Launcher</Button>
  </PopoverLauncher>
  <PopoverContent dialog aria-label="popover-content">
    <PopoverCloser textAlign="right">
      <Button skin="unstyled">
        <Icon iconType="close" size="16p" />
      </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>

<Popover position="bottom" my="11">
  <PopoverLauncher>
    <Button>Popover Launcher</Button>
  </PopoverLauncher>
  <PopoverContent dialog aria-label="popover-content">
    <PopoverCloser textAlign="right">
      <Button skin="unstyled">
        <Icon iconType="close" size="16p" />
      </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>

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>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>Popover launched programatically.</PopoverContent>
      </Popover>
    </FlexBox>
  )
}

Content

Show additional information in-context with the triggering element.
Keep content brief.
Don’t place critical information in a Popover.
- This is considered a UX bad practice as user may miss it.
- Search engines won’t see any information that requires interaction to view. If your use case requires it, ensure the Popover content is part of the page's source HTML on the server.

Interactive elements

Make the trigger element accessible and clickable via keyboard, usually a button. You will need to ensure the trigger element is keyboard-accessible (refer to Keyboard Access).
Use the dialog prop if a Popover contains any interactive elements.
Don’t remove the arrowhead that points to the trigger element.

Layout

Set the offset—the space between the trigger element and the Popover—to 8px unless a special case requires a different value.
Don’t try to manually position the Popover. Use the position prop instead.
Don’t use the expanded prop on any Popover inside a Modal Dialog as the Popover will not display in the desired location.

SWAN doesn’t support tooltip components. Tooltips show contextual information on hover or keyboard focus. However, this behavior is not accessible to keyboard users, screen readers, or users on mobile. The Popover component can be used in much the same way, however, it must be triggered by a click. A Popover can also contain interactive elements.

Popovers are less disruptive and more dynamic than a Modal Dialog as they give succinct additional information in-context.
Appears next to the trigger, pointing to the trigger to show that the popover’s contents are contextual.
Have a max width of 375px.
Closed when the user clicks on anything else on the page.

Modal Dialogs overlay the entire page.
A new “mode” for inputting or reviewing information.
Removes other page distractions for a more focused experience.
Depending on the complexity of the information and the context in which the user accesses it, consider whether a new page should be presented instead of a Modal Dialog.

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.