Popover

<quiet-popover>

stable

since 1.0

Popovers provide additional information or functionality without interrupting the flow of content.

Popovers appear when a corresponding anchor element is clicked. Unlike tooltips, popovers can contain interactive content such as links, buttons, and form controls. They are not modal, so no overlay is shown when open. Popovers will close when the user clicks outside of them or presses Escape. Only one popover can be open at a time.

A gray kitten yawns but it looks like a laugh

Cats love chasing popovers that appear on the screen. I wonder what they would do if they actually caught one. Learn more

<quiet-popover for="popover__overview">
  <div style="display: flex; gap: 1.5rem; align-items: center;">
    <img 
      src="https://images.unsplash.com/photo-1579014868745-23e405c5605d?q=80&w=400&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" 
      alt="A gray kitten yawns but it looks like a laugh"
      style="max-width: 8rem;"
    >
    <div style="display: flex; flex-direction: column; justify-content: space-between; gap: 1.5rem">
      Cats love chasing popovers that appear on the screen. I wonder what they would do if they actually caught one.
      <quiet-button variant="primary" size="sm">Learn more</quiet-button>
    </div>
  </div>
</quiet-popover>

<quiet-button id="popover__overview">Show popover</quiet-button>

Examples Jump to heading

Assigning an anchor Jump to heading

Popover anchors should be <quiet-button> or <button> elements. Use the for attribute on the popover to link it to the anchor's id.

Show popover

I'm just a popover anchored to a button.

I'm just a popover anchored to a native button.

<quiet-button id="popover__anchor-button">Show popover</quiet-button>

<quiet-popover for="popover__anchor-button">
  I'm just a popover anchored to a button.
</quiet-popover>

<br><br>

<button id="popover__anchor-native-button">Show popover</button>

<quiet-popover for="popover__anchor-native-button">
  I'm just a popover anchored to a native button.
</quiet-popover>

The anchor element must be in the DOM when the popover is connected, otherwise the popover won't be attached and a warning will be shown in the console.

Opening and closing popovers Jump to heading

Popovers will be shown when their anchor element is clicked. You can open and close a popover programmatically by obtaining a reference to it and setting the open property to true or false, respectively.

As a convenience, you can add data-popover="close" to any button inside a popover to close it without additional JavaScript.

The button below has data-popover="close" so clicking it will close the popover.

Dismiss

<quiet-popover for="popover__opening">
  <p>The button below has <code>data-popover="close"</code> so clicking it will close the popover.</p>
  <quiet-button data-popover="close" variant="primary">Dismiss</quiet-button>
</quiet-popover>

<quiet-button id="popover__opening">Show popover</quiet-button>

Placement Jump to heading

Use the placement attribute to change the preferred location of the popover in reference to its anchor. The popover will shift to a more optimal location if the preferred placement doesn't have enough room. The default placement is top.

              Top
              I'm on the top

              Bottom
              I'm on the bottom

              Left
              I'm on the left 

              Right
              I'm on the right
            

<quiet-button id="popover__top">Top</quiet-button>
<quiet-popover for="popover__top" placement="top">I'm on the top</quiet-popover>

<quiet-button id="popover__bottom">Bottom</quiet-button>
<quiet-popover for="popover__bottom" placement="bottom">I'm on the bottom</quiet-popover>

<quiet-button id="popover__left">Left</quiet-button>
<quiet-popover for="popover__left" placement="left">I'm on the left </quiet-popover>

<quiet-button id="popover__right">Right</quiet-button>
<quiet-popover for="popover__right" placement="right">I'm on the right</quiet-popover>

Distance Jump to heading

You can change the distance of the popover from the anchor by setting the distance attribute to the desired number of pixels.

              Near
              I'm so near

              Far
              I'm so far
            

<quiet-button id="popover__distance-near">Near</quiet-button>
<quiet-popover for="popover__distance-near" distance="0">I'm so near</quiet-popover>

<quiet-button id="popover__distance-far">Far</quiet-button>
<quiet-popover for="popover__distance-far" distance="30">I'm so far</quiet-popover>

Changing the arrow size Jump to heading

You can change the size of the popover's arrow with the --arrow-size custom property. Set it to 0 to remove the arrow.

              Big arrow
              I have a big arrow

              No arrow
              I don't have an arrow
            

<quiet-button id="popover__big-arrow">Big arrow</quiet-button>
<quiet-popover for="popover__big-arrow" style="--arrow-size: 8px;">I have a big arrow</quiet-popover>

<quiet-button id="popover__no-arrow">No arrow</quiet-button>
<quiet-popover for="popover__no-arrow" style="--arrow-size: 0;">I don't have an arrow</quiet-popover>

Setting a max width Jump to heading

Use the --max-width custom property to change the maximum width of the popover.

              Toggle me
              
                Popovers will usually grow to be a lot wider, but this one has a custom max width.

<quiet-button id="popover__max-width">Toggle me</quiet-button>
<quiet-popover for="popover__max-width" style="--max-width: 160px;">
  Popovers will usually grow to be a lot wider, but this one has a custom max width.
</quiet-popover>

Setting focus on open Jump to heading

To move focus to a specific form control when the popover opens, use the autofocus global attribute.

<quiet-popover for="popover__autofocus">
  <div style="display: flex; flex-direction: column; gap: 1rem;">
    <quiet-text-field autofocus label="New value" size="sm"></quiet-text-field>
    <quiet-button variant="primary" size="sm" data-popover="close">Update</quiet-button>
  </div>
</quiet-popover>

<quiet-button id="popover__autofocus">
  <quiet-icon slot="start" name="edit"></quiet-icon>
  Edit
</quiet-button>

Using popovers as confirmations Jump to heading

A common popover pattern is to get confirmation before performing a destructive action.

              
                  Confirm delete
                  Cancel
                
              Delete

<quiet-popover for="popover__confirmation" placement="right">
  <div style="display: flex; flex-direction: column; gap: 0.5rem;">
    <quiet-button variant="destructive" size="sm" data-popover="close">Confirm delete</quiet-button>
    <quiet-button size="sm" data-popover="close">Cancel</quiet-button>
  </div>
</quiet-popover>

<quiet-button id="popover__confirmation" variant="destructive">Delete</quiet-button>

Using tab lists in popovers Jump to heading

You can use tab lists in popovers to categorize content as needed.

              
                  First
                  Second
                  Third

                  Cats have a unique way of communicating — they can make over 100 vocal sounds, each meaning
                    something different.
                  A cat's sense of smell is much stronger than that of humans, making their noses one of their most
                    important tools.
                  A group of kittens is called a "kindle," a term that perfectly captures the warmth and charm they
                    bring.
                
              Facts about cats

<quiet-popover for="popover__tabs" id="popover__tablist">
  <quiet-tab-list label="Select a tab">
    <quiet-tab panel="first">First</quiet-tab>
    <quiet-tab panel="second">Second</quiet-tab>
    <quiet-tab panel="third">Third</quiet-tab>

    <quiet-tab-panel name="first">Cats have a unique way of communicating — they can make over 100 vocal sounds, each meaning something different.</quiet-tab-panel>
    <quiet-tab-panel name="second">A cat's sense of smell is much stronger than that of humans, making their noses one of their most important tools.</quiet-tab-panel>
    <quiet-tab-panel name="third">A group of kittens is called a "kindle," a term that perfectly captures the warmth and charm they bring.</quiet-tab-panel>
  </quiet-tab-list>
</quiet-popover>

<quiet-button id="popover__tabs">Facts about cats</quiet-button>

<style>
  #popover__tablist::part(content) {
    padding: 0;
  }

  #popover__tablist quiet-tab-list::part(panels) {
    padding: 1rem;
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-popover> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/popover/popover.js';

To manually import <quiet-popover> from npm, use the following code.

import '@quietui/quiet/dist/components/popover/popover.js';

Slots Jump to heading

Popover supports the following slots. Learn more about using slots

Name	Description
(default)	The popover's content. Do not include interactive elements such as button, links, etc. as they won't be accessible to users inside the popover.

Properties Jump to heading

Popover has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`for`	The ID of of popover's anchor element. This must be an interactive/focusable element such as a button and it must be in the same document as the popover.	`string`
`open`	Shows or hides the popover.	`boolean`	`false`
`placement`	The placement of the popover in reference to the anchor. The menu will shift to a more optimal location if the preferred placement doesn't have enough room.	`'top' 'top-start' 'top-end' 'bottom' 'bottom-start' 'bottom-end' 'right' 'right-start' 'right-end' 'left' 'left-start' 'left-end'`	`'top'`
`distance`	The distance of the popover from its anchor.	`number`	`8`
`offset`	The offset of the popover along its trigger.	`number`	`0`

Events Jump to heading

Popover dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-open`	Emitted when the popover is instructed to open but before it is shown.
`quiet-opened`	Emitted when the popover has opened and the animation has completed.
`quiet-close`	Emitted when the popover is dismissed but before it is hidden.
`quiet-closed`	Emitted when the popover has closed. and the animation has completed.

CSS custom properties Jump to heading

Popover supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties

Name	Description	Default
`--arrow-size`	The size of the arrow. Set this to `0` to hide the arrow.	`0.3125rem`
`--max-width`	The maximum width the popover be before wrapping.	`25rem`
`--show-duration`	The duration of the show/hide animation.	`100ms`

CSS parts Jump to heading

Popover exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`dialog`	The element that powers the popover, a `<dialog>` element.	`::part(dialog)`
`content`	The element that wraps the popover's content.	`::part(content)`
`arrow`	The popover's arrow. To change the arrow's size, use `--arrow-size` instead.	`::part(arrow)`

Custom States Jump to heading

Popover has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`open`	Applied when the popover is open.	`:state(open)`

Popover

Examples Jump to heading #

Assigning an anchor Jump to heading #

Opening and closing popovers Jump to heading #

Placement Jump to heading #

Distance Jump to heading #

Changing the arrow size Jump to heading #

Setting a max width Jump to heading #

Setting focus on open Jump to heading #

Using popovers as confirmations Jump to heading #

Using tab lists in popovers Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Events Jump to heading #

CSS custom properties Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #