Popover

Basic Usage

A basic popover can be created with PopoverTrigger and PopoverContent.

When creating a popover, you need to pass the same value to the trigger’s target and content’s id property.

<script>
  import { PopoverTrigger, PopoverContent } from '@splendidlabz/svelte'
</script>

<PopoverTrigger target="popover">Pop Top</PopoverTrigger>
<PopoverContent id="popover">Popover Content</PopoverContent>

---
import { PopoverTrigger, PopoverContent } from '@splendidlabz/svelte'
---

<PopoverTrigger target="popover" client:load>Pop Top</PopoverTrigger>
<PopoverContent id="popover" client:load>Popover Content</PopoverContent>

Close Button

You can create a close button with PopoverCloseButton.

<script>
  import {
    PopoverTrigger,
    PopoverContent,
    PopoverCloseButton,
  } from '@splendidlabz/svelte'
</script>

<PopoverTrigger target="Popover">Pop Top</PopoverTrigger>
<PopoverContent id="Popover">
  <div class="flex items-center gap-4">
    <div>Popover Content</div>
    <PopoverCloseButton />
  </div>
</PopoverContent>

---
import {
  PopoverTrigger,
  PopoverContent,
  PopoverCloseButton,
} from '@splendidlabz/svelte'
---

<PopoverTrigger target="Popover" client:load>Pop Top</PopoverTrigger>
<PopoverContent id="Popover" client:load>
  <div class="flex items-center gap-4">
    <div>Popover Content</div>
    <PopoverCloseButton client:load />
  </div>
</PopoverContent>

Random ID

If you do not wish to manually name the id and target properties, you can use randomString from Splendid Utils to create a DOM-ready random string. This can sometimes make things a tiny bit easier.

<script>
  import { PopoverTrigger, DrawerContent } from '@splendidlabz/svelte'
  import { randomString } from '@splendidlabz/utils'
  const id = randomString()
</script>

<PopoverTrigger target={id}>Pop Top</PopoverTrigger>
<DrawerContent {id}>Drawer Content</DrawerContent>

---
import { PopoverTrigger, PopoverContent } from '@splendidlabz/svelte'
import { randomString } from '@splendidlabz/utils'
const id = randomString()
---

<PopoverTrigger target={id} client:load>Pop Top</PopoverTrigger>
<PopoverContent {id} client:load> Drawer Content </PopoverContent>

Popover Trigger

PopoverTrigger creates a trigger button that opens PopoverContent when clicked.

<PopoverTrigger target="popover">Pop Top</PopoverTrigger>

<PopoverTrigger target="popover" client:load>Pop Top</PopoverTrigger>

Show

If you want to show the popover by default (great for debugging purposes), you can set show to true.

<PopoverTrigger ... show={true}>Pop Top</PopoverTrigger>

<PopoverTrigger ... show={true} client:load>Pop Top</PopoverTrigger>

Show On Hover

If you want to show the popover on hover, you can set showOnHover to true. You can also control the delay before the popover closes by setting hoverCloseDelay to a number in milliseconds.

<PopoverTrigger ... options={{ showOnHover: true, hoverCloseDelay: 120 }}>
  Pop Top
</PopoverTrigger>

<PopoverTrigger
  ...
  options={{ showOnHover: true, hoverCloseDelay: 120 }}
  client:load
>
  Pop Top
</PopoverTrigger>

Multiple popovers

Normally, only one popover will be opened by default. So if you open a new popover, the previous one will close automatically.

If you wish to have multiple popovers opened, you can set closeOthers to false on them all.

<PopoverTrigger ... options={{ closeOthers: false }}>Pop Top</PopoverTrigger>

<PopoverTrigger ... options={{ closeOthers: false }} client:load>
  Pop Top
</PopoverTrigger>

Other options

PopoverTrigger is built on top of DisclosureTrigger and inherits all of its options. In addition to the above properties, you can pass other DisclosureTrigger properties into PopoverTrigger.

All other unnamed properties will be passed directly to the underlying button element.

Popover Content

PopoverContent contains content that should show up when PopoverTrigger is clicked.

Placements

PopoverContent has 12 placement options:

• top, top-start, top-end
• left, left-start, left-end
• right, right-start, right-end
• bottom, bottom-start, bottom-end

top, left, right, and bottom refer to its position on the main axis. while start and end refers to its position on the cross axis. The following example would make more sense:

<PopoverContent id="Popover" options={{ placement: 'top-end' }}>
  Popover Content
</PopoverContent>

<PopoverContent id="Popover" options={{ placement: 'top-end' }} client:load>
  Popover Content
</PopoverContent>

If there isn’t enough space to display the popover on the main axis, it will automatically be displayed in the opposite direction. If there is still insuffient space, it will be displayed in the other axis, whenever possible.

See Portal below for an example on how they will be displayed.

Portal

By default, PopoverContent will be moved out from their default DOM locations and inserted as a direct descendant of the <body> element. This prevents PopoverContent from being constrained (or even cut-off) by parent elements.

If you wish to disable this behaviour, set the portal option to false.

<PopoverContent id="Popover" options={{ portal: false }}>
  Popover Content
</PopoverContent>

<PopoverContent id="Popover" options={{ portal: false }} client:load>
  Popover Content
</PopoverContent>

Offset

You can set an offset value in px, em or rem. em and rem values will be calculated and output in pixels accordingly.

<PopoverContent id="Popover" options={{ offset: '1rem' }}>
  Popover Content
</PopoverContent>

<PopoverContent id="Popover" options={{ offset: '1rem' }} client:load>
  Popover Content
</PopoverContent>

Arrows

Set arrow to true if you want your popover to contain arrows. These arrows will be placed accordingly to the placement you have set. They also take into account the border-radius of the popover so they look right.

<PopoverContent id="Popover" options={{ arrow: true }}>
  Popover Content
</PopoverContent>

<PopoverContent id="Popover" options={{ arrow: true }} client:load>
  Popover Content
</PopoverContent>

You can change the arrow’s width by setting arrowWidth.

<PopoverContent id="Popover" options={{ arrow: true, arrowWidth: '0.75rem' }}>
  Popover Content
</PopoverContent>

<PopoverContent
  id="Popover"
  options={{ arrow: true, arrowWidth: '0.75rem' }}
  client:load
>
  Popover Content
</PopoverContent>

When arrows are set, offset will be the distance between PopoverTrigger and the edge of the arrow.

<PopoverContent id="Popover" options={{ arrow: true, offset: 0 }}>
  Popover Content
</PopoverContent>

<PopoverContent id="Popover" options={{ arrow: true, offset: 0 }} client:load>
  Popover Content
</PopoverContent>

If you encounter rounding issues with arrow, you can use arrowDelta to correct those rounding errors manually. This will give you precise control over the final placement of the arrow in the main axis.

<PopoverContent id="Popover" options={{ arrow: true, arrowDelta: 1 }}>
  Popover Content
</PopoverContent>

<PopoverContent
  id="Popover"
  options={{ arrow: true, arrowDelta: 1 }}
  client:load
>
  Popover Content
</PopoverContent>

Other options

PopoverContent is built on top of DisclosureContent and inherits all of its options. In addition to the above properties, you can pass other DisclosureContent properties into PopoverContent.

Events

PopoverContent emits the following events:

• open - emitted when the PopoverContent is opened
• close - emitted when the PopoverContent is closed

<script>
  function opened()  { /* Do something */}
  function closed () { /* Do something */}
</script>

<PopoverContent on:open={opened} on:close={closed}> ... </PopoverContent>

Popover Close Button

PopoverCloseButton creates a button that closes the Popover when clicked. It is normally used inside PopoverContent, but it can also be used elsewhere.

If you’re using PopoverCloseButton outside PopoverContent, you’ll need to give it a target which corresponds to the Popover’s ID.

<PopoverCloseButton target="popover" />

<PopoverCloseButton target="popover" client:load />

Custom Icon

PopoverCloseButton uses Tabler’s x icon by default.

If you wish to change the icon, simply set the icon property to your desired icon. See SVG for more information on using icon.

<PopoverCloseButton icon="ph:x"/>

<PopoverCloseButton icon="ph:x" client:load />

Custom Content

You can insert HTML into PopoverCloseButton if you wish to create a custom close button.

<PopoverCloseButton>Close</PopoverCloseButton>

<PopoverCloseButton client:load>Close</PopoverCloseButton>

Intro

Popover is built on top of Disclosure and inherits all its accessibility features. For your convenience, we have listed some of the most important features and how to use them here.

Closing and dismissing

Users can dismiss the popover via three main ways:

1. Clicking^* on the close button
2. Clicking outside PopoverContent
3. Using the Esc key

^*: “Clicking” includes using Enter and Space keys because we used the standard <button> element.

You can disable the second and third dismissal methods by setting their respective options to false:

<PopoverContent
  id="popover"
  options={{
    closeOnOutsideClick: false,
    closeOnEscapeButton: false,
  }}
>
  <!-- Popover content goes here -->
</PopoverContent>

<PopoverContent
  id="popover"
  options={{
    closeOnOutsideClick: false,
    closeOnEscapeButton: false,
  }}
  client:load
>
  {/* Popover content goes here */}
</PopoverContent>

Focusing

This section covers how Popover handles focus.

Focusing when opening

When PopoverContent opens, it will automatically be focused, so keyboard users and screen readers can start interacting with it immediately.

Focusing when closing

If a user closes PopoverContent with the Esc key or by clicking on PopoverCloseButton, we will focus on the PopoverTrigger. This lets keyboard and screen reader users navigate to the next item without using a mouse.

To disable this behaviour, you can set focusTriggerOnClose to false:

<PopoverContent id="popover" options={{ focusTriggerOnClose: false }}>
  Popover Content
</PopoverContent>

<PopoverContent
  id="popover"
  options={{ focusTriggerOnClose: false }}
  client:load
>
  Popover Content
</PopoverContent>

Focus Management

PopoverContent handles focus in the following way:

• When the user presses Tab on the final item inside PopoverContent, PopoverContent will close and focus will move onto the next item after PopoverTrigger.
• When user presses Shift + Tab on the first item inside PopoverContent will not close, and focus goes back to PopoverTrigger.

We built this behaviour because it seems to be most sensible for screen readers and keyboard users.

Aria stuff to know

Labeling

The following is true for labelling Popover components:

• Labelling PopoverTrigger is optional if the text content is clear enough.
• Labelling PopoverContent is necessary.
• PopoverCloseButton has a default label set to “Close dialog”.

You can use aria-label or aria-labelledby to give PopoverTrigger, PopoverContent, and PopoverCloseButton accessible names.

<PopoverContent ... aria-label="Popover Content">...</PopoverContent>

<PopoverContent ... aria-label="Popover Content" client:load>
  ...
</PopoverContent>

Roles

PopoverContent needs a role to be accessible. We have set it to dialog because that’s what you would use for most use-cases. (Don’t worry about other roles because our others components would handle those roles for you).

That said, you can change PopoverContent’s role if you want to. If the role is menu, Listbox, grid, or tree, you should also set PopoverTrigger’s aria-haspopup value to the same role. If not, set aria-haspopup to null.

<PopoverTrigger target="popover" aria-haspopup="menu">...</PopoverTrigger>
<PopoverContent id="popover" role="menu">...</PopoverContent>

<PopoverTrigger target="popover" aria-haspopup="menu" client:load>
  ...
</PopoverTrigger>
<PopoverContent id="popover" role="menu" client:load>...</PopoverContent>

Basic Styles

You can import the basic styles for Popover through Splendid Styles.

@use '@splendidlabz/styles';

@import '@splendidlabz/styles/css';

HTML Output

Popover Trigger

PopoverTrigger produces the following output:

<button ... class="Button PopoverTrigger">...</button>

Popover Content

PopoverContent produces the following output.

<div id="content" role="dialog" tabindex="-1" class="PopoverContent">...</div>

If you set the arrow option to true, PopoverContent will include a PopoverArrow element.

<div id="content" role="dialog" tabindex="-1" class="PopoverContent">
  <!-- Your content here -->
  <div class="PopoverArrow" />
</div>

Popover Close Button

PopoverCloseButton produces the following HTML:

<button class="PopoverCloseButton Button-icon">
  <svg>...</svg>
</button>

If content is passed into PopoverCloseButton, the content will replace the <svg> element.

<button class="PopoverCloseButton Button-icon">...</button>

Classes and Properties

Popover Trigger

The following classes are used by PopoverTrigger

These properties can be used to add classes to PopoverTrigger.

Popover Content

The following classes are used by PopoverContent

These properties can be used to add classes to PopoverContent.

Popover Close Button

The following classes are used by PopoverCloseButton

These properties can be used to add classes to PopoverCloseButton.

Popover Trigger

Properties

The following properties affect the functionality of PopoverTrigger.

Popover Content

Properties

The following properties affect the functionality of PopoverContent.

Options

PopoverContent has these options:

Popover Close Button

Properties

You can provide the following properties to PopoverCloseButton.