Skip to main content

Popover

The popover component displays content in an overlay anchored to the button that opens it. Use popover for secondary information and actions that don't need to occupy permanent space on the page.

A popover is closed by default and is opened by a button whose commandFor matches the popover's id. It renders in the browser's top layer, so it escapes the bounds of surrounding containers without any positioning code.

Support
Targets (50)

Supported targets

Anchor to Use casesUse cases

  • Secondary actions: Group related actions behind a single trigger.
  • Supporting detail: Show supplementary data without leaving the page.
  • Display settings: Let merchants configure what a table or list shows.
  • Filtering: Collect filter choices and apply them on confirmation.

Preview

html

<s-button commandFor="product-options-popover">Product options</s-button>

<s-popover id="product-options-popover">
<s-stack direction="block">
<s-button variant="tertiary">Import</s-button>
<s-button variant="tertiary">Export</s-button>
</s-stack>
</s-popover>

Anchor to PropertiesProperties

Configure the following properties on the popover component.

Anchor to blockSize
blockSize
Default: 'auto'

The vertical size of the element in standard layouts (height in left-to-right or right-to-left writing modes).

Block size adjusts based on the writing direction: in horizontal layouts, it controls the height; in vertical layouts, it controls the width. This ensures consistent behavior across different text directions.

Learn more about the block-size property.

  • SizeUnits: Specific size values in pixels, percentages, or zero for precise control.
  • auto: Automatically sizes based on content and layout constraints.
Anchor to inlineSize
inlineSize
Default: 'auto'

The horizontal size of the element in standard layouts (width in left-to-right or right-to-left writing modes).

Inline size adjusts based on the writing direction: in horizontal layouts, it controls the width; in vertical layouts, it controls the height. This ensures consistent behavior across different text directions.

Learn more about the inline-size property.

  • SizeUnits: Specific size values in pixels, percentages, or zero for precise control.
  • auto: Automatically sizes based on content and layout constraints.
Anchor to maxBlockSize
maxBlockSize
Default: 'none'

The maximum vertical size of the element in standard layouts (max-height in left-to-right or right-to-left writing modes).

Prevents the element from becoming larger than this size along the block axis.

Learn more about the max-block-size property.

Anchor to maxInlineSize
maxInlineSize
Default: 'none'

The maximum horizontal size of the element in standard layouts (max-width in left-to-right or right-to-left writing modes).

Prevents the element from becoming larger than this size along the inline axis.

Learn more about the max-inline-size property.

Anchor to minBlockSize
minBlockSize
Default: '0'

The minimum vertical size of the element in standard layouts (min-height in left-to-right or right-to-left writing modes).

Prevents the element from becoming smaller than this size along the block axis.

Learn more about the min-block-size property.

Anchor to minInlineSize
minInlineSize
Default: '0'

The minimum horizontal size of the element in standard layouts (min-width in left-to-right or right-to-left writing modes).

Prevents the element from becoming smaller than this size along the inline axis.

Learn more about the min-inline-size property.

Anchor to EventsEvents

The popover component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to afterhide
afterhide
<TTagName> | null

A callback fired after the popover is hidden.

Anchor to aftershow
aftershow
<TTagName> | null

A callback fired after the popover is shown.

Anchor to aftertoggle
aftertoggle
<TTagName> | null

A callback fired after the popover is toggled.

Anchor to hide
hide
<TTagName> | null

A callback fired when the popover is hidden.

Anchor to show
show
<TTagName> | null

A callback fired when the popover is shown.

Anchor to toggle
toggle
<TTagName> | null

A callback fired when the popover is toggled.

Anchor to SlotsSlots

The popover component supports slots for additional content placement within the component. Learn more about using slots.

Anchor to children
children
HTMLElement

The content displayed within the popover component, which appears in an overlay positioned relative to its trigger element.

Anchor to ExamplesExamples

Anchor to Show a menu of actionsShow a menu of actions

Group related actions behind a single trigger. This example shows a button that opens a popover containing tertiary import and export actions.

Preview

html

<s-button commandFor="product-options-popover">Product options</s-button>

<s-popover id="product-options-popover">
<s-stack direction="block">
<s-button variant="tertiary">Import</s-button>
<s-button variant="tertiary">Export</s-button>
</s-stack>
</s-popover>

Anchor to Display a notification listDisplay a notification list

Surface recent activity without navigating away. This example shows a notification button that opens a popover listing three updates separated by dividers.

Preview

html

<s-button commandFor="notifications-popover" icon="notification">
Notifications
</s-button>

<s-popover id="notifications-popover">
<s-box padding="base">
<s-stack gap="small-200">
<s-stack gap="small">
<s-heading>New order received</s-heading>
<s-paragraph color="subdued">
Order #1234 was placed 5 minutes ago
</s-paragraph>
</s-stack>

<s-divider />

<s-stack gap="small">
<s-heading>Low inventory alert</s-heading>
<s-paragraph color="subdued">
3 products are running low on stock
</s-paragraph>
</s-stack>

<s-divider />

<s-stack gap="small">
<s-heading>Payment processed</s-heading>
<s-paragraph color="subdued">
$250.00 payment confirmed for order #1230
</s-paragraph>
</s-stack>
</s-stack>
</s-box>
</s-popover>

Anchor to Configure table display optionsConfigure table display options

Let merchants choose which columns a table shows. This example shows a settings button that opens a popover with a choice list and a primary button to apply the selection.

Preview

html

<s-button commandFor="table-settings-popover" icon="settings">
Columns
</s-button>

<s-popover id="table-settings-popover">
<s-box padding="base">
<s-stack gap="small-200">
<s-stack gap="small">
<s-heading>Choose columns to display</s-heading>
<s-choice-list label="Select columns to display" name="columns" multiple>
<s-choice value="sku" selected>Sku</s-choice>
<s-choice value="inventory" selected>Inventory</s-choice>
<s-choice value="price" selected>Price</s-choice>
<s-choice value="vendor">Vendor</s-choice>
<s-choice value="type">Product type</s-choice>
</s-choice-list>
</s-stack>
<s-button variant="primary" commandFor="table-settings-popover" command="--hide">Apply changes</s-button>
</s-stack>
</s-box>
</s-popover>

Anchor to Show inventory detailsShow inventory details

Expand on a value shown elsewhere on the page. This example shows an info button that opens a popover breaking stock down into available, reserved, and in-transit quantities.

Preview

html

<s-button commandFor="stock-popover" icon="info">
Stock details
</s-button>

<s-popover id="stock-popover">
<s-box padding="base">
<s-stack gap="small">
<s-stack gap="small-200">
<s-stack direction="inline" justifyContent="space-between">
<s-text color="subdued">Available</s-text>
<s-text>127 units</s-text>
</s-stack>

<s-stack direction="inline" justifyContent="space-between">
<s-text color="subdued">Reserved</s-text>
<s-text>15 units</s-text>
</s-stack>

<s-stack direction="inline" justifyContent="space-between">
<s-text color="subdued">In transit</s-text>
<s-text>50 units</s-text>
</s-stack>
</s-stack>

<s-divider />

<s-stack direction="inline" justifyContent="space-between">
<s-text>Total stock</s-text>
<s-text>192 units</s-text>
</s-stack>

<s-button variant="secondary">View full inventory report</s-button>
</s-stack>
</s-box>
</s-popover>

Anchor to Filter with apply and clearFilter with apply and clear

Collect filter choices and close the popover once the merchant confirms. This example sets inlineSize for a wider overlay and closes it from buttons that target the popover with command="--hide".

Preview

html

<s-button commandFor="filter-popover" id="filter-btn">Filter</s-button>

<s-popover id="filter-popover" inlineSize="250px">
<s-box padding="base">
<s-stack direction="block" gap="base">
<s-heading>Filter by status</s-heading>

<s-choice-list id="status-filter" name="status" label="Filter by status" labelAccessibilityVisibility="exclusive">
<s-choice value="all" selected>All products</s-choice>
<s-choice value="active">Active</s-choice>
<s-choice value="draft">Draft</s-choice>
</s-choice-list>

<s-stack direction="inline" gap="base">
<s-button variant="primary" id="apply-filter" commandFor="filter-popover" command="--hide">Apply</s-button>
<s-button id="clear-filter" commandFor="filter-popover" command="--hide">Clear</s-button>
</s-stack>
</s-stack>
</s-box>
</s-popover>

<script>
const filterBtn = document.getElementById('filter-btn');
const choiceList = document.getElementById('status-filter');

document.getElementById('apply-filter').addEventListener('click', () => {
const selected = choiceList.values[0];
filterBtn.textContent = selected !== 'all' ? `Filter: ${selected}` : 'Filter';
});

document.getElementById('clear-filter').addEventListener('click', () => {
choiceList.values = ['all'];
filterBtn.textContent = 'Filter';
});
</script>

Anchor to Best practicesBest practices

  • Reserve popovers for secondary content: Primary content and primary actions belong on the page. Use a popover for detail or actions that only some merchants need, some of the time.
  • Trigger on press, never on hover: A popover manages focus and returns it to the activator on close, which hover activation breaks. If you want content to appear on hover, use tooltip instead.
  • Label the activator with the content: Name the button after what opens, using the {verb}+{noun} format or a plain noun like Columns. Avoid vague triggers like More or Options.
  • Use a default or tertiary button as the trigger: A primary button signals the main action on the page, which a popover isn't.
  • Close the popover after a confirming action: When a popover collects input, have the confirming button target it with command="--hide" so the merchant isn't left dismissing it manually.
  • Size only when the content needs it: The popover sizes to its content by default. Reach for inlineSize or maxBlockSize only when the default is genuinely too narrow or too tall.

Anchor to LimitationsLimitations

  • Popovers render in the top layer and reposition to stay within the viewport, but in very constrained spaces the overlay can still be cut off. Prefer compact content.
  • Size properties accept fixed values such as 250px or 50%. They aren't responsive, so a size that suits a wide viewport can crowd a narrow one.
  • The activator relationship is established by commandFor matching the popover's id. If the id is missing, duplicated, or the popover isn't in the document, the trigger silently does nothing.
  • A popover isn't a modal. It doesn't trap focus or block interaction with the rest of the page, so don't use it for content that must be acknowledged.
Was this page helpful?