sp-popover

NPM 1.0.1

View Storybook

Try it on webcomponents.dev
Overview API Changelog

Overview

An <sp-popover> is used to display transient content (menus, options, additional actions etc.) and appears when clicking/tapping on a source (tools, buttons, etc.) It stands out via its visual style (stroke and drop shadow) and floats on top of the rest of the interface. This component does not implement the actual overlay behavior and interactions. This is handled by the Overlay system.

Usage

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/popover

Import the side effectful registration of <sp-popover> via:

import '@spectrum-web-components/popover/sp-popover.js';

When looking to leverage the Popover base class as a type and/or for extension purposes, do so via:

import { Popover } from '@spectrum-web-components/popover';

Anatomy

<div
    style="
        position: relative;
        height: 100px;
    "
>
    <sp-popover open>
        Cupcake ipsum dolor sit amet jelly beans. Chocolate jelly caramels.
    </sp-popover>
</div>

Options

Default with no tip

Default popover with no tip and no placement. Popovers will fill up the space of their containing element by default. The default popover has no padding.

<div
    style="
        position: relative;
        height: 180px;
        max-width: 320px;
    "
>
    <sp-popover variant="default" open>
        <h2>Popover title</h2>
        <p>
            Cupcake ipsum dolor sit amet jelly beans. Chocolate jelly caramels.
            Icing soufflé chupa chups donut cheesecake. Jelly-o chocolate cake
            sweet roll cake danish candy biscuit halvah
        </p>
    </sp-popover>
</div>

Dialog popovers

To apply a managed amount of padding within your <sp-popover>, you may choose to wrap your slotted content in an <sp-dialog> element, as seen below:

<div
    style="
        position: relative;
        height: 250px;
        max-width: 320px;
    "
>
    <sp-popover open>
        <sp-dialog>
            <h3 slot="heading">Popover title</h3>
            Cupcake ipsum dolor sit amet jelly beans. Chocolate jelly caramels.
            Icing soufflé chupa chups donut cheesecake. Jelly-o chocolate cake
            sweet roll cake danish candy biscuit halvah
        </sp-dialog>
    </sp-popover>
</div>

Popover with tip

The placement attribute can be used to customize how the <sp-popover> points to its related content. placement="top" will point down to the related content from the top, etc.

Top 
<div
    style="
        position: relative;
        height: 250px;
        max-width: 320px;
    "
>
    <sp-popover placement="top" tip open>
        <sp-dialog>
            <h3 slot="heading">Popover title</h3>
            Cupcake ipsum dolor sit amet jelly beans. Chocolate jelly caramels.
            Icing soufflé chupa chups donut cheesecake. Jelly-o chocolate cake
            sweet roll cake danish candy biscuit halvah
        </sp-dialog>
    </sp-popover>
</div>
 Right 
<div
    style="
        position: relative;
        height: 200px;
        max-width: 320px;
    "
>
    <sp-popover placement="right" tip open>
        <sp-dialog>
            <h3 slot="heading">Popover title</h3>
            Cupcake ipsum dolor sit amet jelly beans. Chocolate jelly caramels.
            Icing soufflé chupa chups donut cheesecake. Jelly-o chocolate cake
            sweet roll cake danish candy biscuit halvah
        </sp-dialog>
    </sp-popover>
</div>
 Bottom 
<div
    style="
        position: relative;
        height: 200px;
        max-width: 320px;
    "
>
    <sp-popover placement="bottom" tip open>
        <sp-dialog>
            <h3 slot="heading">Popover title</h3>
            Cupcake ipsum dolor sit amet jelly beans. Chocolate jelly caramels.
            Icing soufflé chupa chups donut cheesecake. Jelly-o chocolate cake
            sweet roll cake danish candy biscuit halvah
        </sp-dialog>
    </sp-popover>
</div>
 Left 
<div
    style="
        position: relative;
        height: 200px;
        max-width: 320px;
    "
>
    <sp-popover placement="left" tip open>
        <sp-dialog>
            <h3 slot="heading">Popover title</h3>
            Cupcake ipsum dolor sit amet jelly beans. Chocolate jelly caramels.
            Icing soufflé chupa chups donut cheesecake. Jelly-o chocolate cake
            sweet roll cake danish candy biscuit halvah
        </sp-dialog>
    </sp-popover>
</div>

Accessibility

For components used with a popover, see the accessibility guidelines of the particular component.

Attributes and Properties

Property Attribute Type Default Description open open boolean false Whether the popover is visible or not. placement placement "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" tip tip boolean false

Slots

Name Description default slot content to display within the Popover

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/popover

1.0.0 (2024-10-31)

BREAKING CHANGES

  • remove popover's dialog property (#4751)

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/popover

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/popover

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/popover

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/popover

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/popover

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/popover

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/popover

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/popover

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/popover

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/popover

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/popover

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/popover

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/popover

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/popover

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/popover

0.42.0 (2024-03-19)

Bug Fixes

  • styles, theme: surface exports that omit Spectrum Vars proactively (#4142) (5b524c1)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/popover

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/popover

0.41.0 (2024-02-13)

Bug Fixes

  • popover: correct tip delivery size (#4018) (4ff403e)

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/popover

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/popover

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/popover

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/popover

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/popover

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/popover

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/popover

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/popover

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/popover

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/popover

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/popover

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/popover

0.37.0 (2023-08-18)

Features

  • popover: leverage Overlay v2 (cde0a16)

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/popover

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/popover

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/popover

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/popover

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/popover

0.32.0 (2023-06-01)

Features

  • popover: use core tokens (68328cc)

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/popover

0.30.0 (2023-05-03)

Bug Fixes

  • add content flow fallbacks to the position manager (c008957)
  • allow ActiveOverlay to manage open state (a7c4cff)
  • constrain overlay to available window size (9729b55)
  • correct @element jsDoc listing across library (c97a632)
  • correct max size calculation for overlays (0585f7f)
  • include "type" in package.json, generate custom-elements.json (1a8d716)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • menu: add support for submenu interactions (68399af)
  • position tip shapes for bi-directional delivery (35654de)
  • stop merging selectors in a way that alters the cascade (369388f)
  • tooltip: correct arrow orientation, remove popper-arrow-rotate (fcd6ea2)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update screen reader interface with menu items list (16756b5)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use latest @spectrum-css/* versions (c35eb86)
  • use less restrictive overlay sizing (f6917aa)

Features

  • action-button: add action button pattern (03ac00a)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • allow activation of longpress content (55e71fd)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • popover: update spectrum css input (0f7a00e)
  • rework overlays to use popper (e17d1bb)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use @adobe/spectrum-css@2.15.1 (3918888)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)
  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts

  • Revert "chore: release new versions" (a6d655d)

0.12.17 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/popover

0.12.16 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/popover

0.12.15 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/popover

0.12.14 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/popover

0.12.13 (2023-02-13)

Note: Version bump only for package @spectrum-web-components/popover

0.12.12 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/popover

0.12.11 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/popover

0.12.10 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/popover

0.12.9 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/popover

0.12.8 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/popover

0.12.7 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/popover

0.12.6 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/popover

0.12.5 (2022-10-17)

Note: Version bump only for package @spectrum-web-components/popover

0.12.4 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/popover

0.12.3 (2022-09-15)

Note: Version bump only for package @spectrum-web-components/popover

0.12.2 (2022-09-14)

Note: Version bump only for package @spectrum-web-components/popover

0.12.1 (2022-08-24)

Note: Version bump only for package @spectrum-web-components/popover

0.12.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.11.17 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/popover

0.11.16 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/popover

0.11.15 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/popover

0.11.14 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/popover

0.11.13 (2022-05-27)

Bug Fixes

  • add content flow fallbacks to the position manager (c008957)

0.11.12 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/popover

0.11.11 (2022-04-21)

Bug Fixes

  • use less restrictive overlay sizing (f6917aa)

0.11.10 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/popover

0.11.9 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/popover

0.11.8 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/popover

0.11.7 (2022-03-04)

Bug Fixes

  • menu: add support for submenu interactions (68399af)

0.11.6 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/popover

0.11.5 (2022-02-02)

Note: Version bump only for package @spectrum-web-components/popover

0.11.4 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/popover

0.11.3 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/popover

0.11.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/popover

0.11.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/popover

0.11.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/popover

0.10.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/popover

0.10.0 (2021-11-02)

Bug Fixes

  • update screen reader interface with menu items list (16756b5)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.9.18 (2021-10-12)

Note: Version bump only for package @spectrum-web-components/popover

0.9.17 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/popover

0.9.16 (2021-09-13)

Note: Version bump only for package @spectrum-web-components/popover

0.9.15 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.9.14 (2021-08-17)

Note: Version bump only for package @spectrum-web-components/popover

0.9.13 (2021-08-03)

Note: Version bump only for package @spectrum-web-components/popover

0.9.12 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/popover

0.9.11 (2021-07-01)

Note: Version bump only for package @spectrum-web-components/popover

0.9.10 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/popover

0.9.9 (2021-06-07)

Note: Version bump only for package @spectrum-web-components/popover

0.9.8 (2021-05-24)

Note: Version bump only for package @spectrum-web-components/popover

0.9.7 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/popover

0.9.6 (2021-04-15)

Note: Version bump only for package @spectrum-web-components/popover

0.9.5 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/popover

0.9.4 (2021-03-29)

Bug Fixes

  • correct max size calculation for overlays (0585f7f)

0.9.3 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/popover

0.9.2 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/popover

0.9.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/popover

0.9.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.8.0 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

Features

  • allow activation of longpress content (55e71fd)

0.7.1 (2021-01-28)

Bug Fixes

  • position tip shapes for bi-directional delivery (35654de)
  • tooltip: correct arrow orientation, remove popper-arrow-rotate (fcd6ea2)
  • allow ActiveOverlay to manage open state (a7c4cff)

0.7.0 (2021-01-21)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • popover: update spectrum css input (0f7a00e)

0.6.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • popover: update spectrum css input (0f7a00e)

0.5.4 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/popover

0.5.3 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.5.2 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.5.1 (2020-09-15)

Note: Version bump only for package @spectrum-web-components/popover

0.5.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)

0.4.6 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/popover

0.4.5 (2020-08-13)

Note: Version bump only for package @spectrum-web-components/popover

0.4.4 (2020-08-13)

Note: Version bump only for package @spectrum-web-components/popover

0.4.3 (2020-08-05)

Note: Version bump only for package @spectrum-web-components/popover

0.4.2 (2020-07-24)

Note: Version bump only for package @spectrum-web-components/popover

0.4.1 (2020-07-22)

Note: Version bump only for package @spectrum-web-components/popover

0.4.0 (2020-07-17)

Features

  • leverage "exports" field in package.json (321abd7)

0.3.10 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/popover

0.3.9 (2020-05-08)

Note: Version bump only for package @spectrum-web-components/popover

0.3.8 (2020-05-08)

Bug Fixes

  • constrain overlay to available window size (9729b55)

0.3.7 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.3.6 (2020-04-10)

Note: Version bump only for package @spectrum-web-components/popover

0.3.5 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/popover

0.3.4 (2020-03-16)

Note: Version bump only for package @spectrum-web-components/popover

0.3.3 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/popover

0.3.2 (2020-02-24)

Note: Version bump only for package @spectrum-web-components/popover

0.3.1 (2020-02-05)

Note: Version bump only for package @spectrum-web-components/popover

0.3.0 (2020-01-30)

Features

  • rework overlays to use popper (e17d1bb)

0.2.2 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/popover

0.2.1 (2019-11-27)

Bug Fixes

  • include "type" in package.json, generate custom-elements.json (1a8d716)

0.2.0 (2019-11-19)

Features

  • use @adobe/spectrum-css@2.15.1 (3918888)

0.1.4 (2019-10-14)

Performance Improvements

  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.3 (2019-10-03)

Note: Version bump only for package @spectrum-web-components/popover