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

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.