Popover

Popovers provide a contextual space attached to an element in an upper z-index layer where you can include any kind of HTML code related to the trigger.

Examples

Base

Popover components are absolutely positioned. For this example we have forced a relative position.

Popover content

Web Component
HTML Blueprint

Remove the active attribute to hide the popover. Use the variant="text" attribute to display text content in a <p>.

<chi-popover variant="text" active>
  Popover content
</chi-popover>

Remove the -active class to hide the popover.

<section class="chi-popover -active" aria-label="Popover Title" aria-modal="true" role="dialog">
  <div class="chi-popover__content">
    <p class="chi-popover__text">Popover content</p>
  </div>
</section>

Titled

Popover content

Web Component
HTML Blueprint

Use the title attribute to display a title.

<chi-popover title="Popover title" variant="text" active>
  Popover content
</chi-popover>

Add chi-popover__header and chi-popover__title to display a title.

<section class="chi-popover -active" aria-label="Popover Title" aria-modal="true" role="dialog">
  <header class="chi-popover__header">
    <h2 class="chi-popover__title">Popover Title</h2>
  </header>
  <div class="chi-popover__content">
    <p class="chi-popover__text">Popover content</p>
  </div>
</section>

Arrow

Popovers support arrows to indicate the element they originate from. Arrows can be located anywhere around the Popover.

Top

Popover content

Right

Popover content

Bottom

Popover content

Left

Popover content

Web Component
HTML Blueprint

Add the attribute arrow and use the attribute position with the values: top, right, bottom and left to position the arrow in the proper place.

<!-- Top -->
<chi-popover position="top" variant="text" active arrow>
  Popover content
</chi-popover>

<!-- Right -->
<chi-popover position="right" variant="text" active arrow>
  Popover content
</chi-popover>

<!-- Bottom -->
<chi-popover position="bottom" variant="text" active arrow>
  Popover content
</chi-popover>

<!-- Left -->
<chi-popover position="left" variant="text" active arrow>
  Popover content
</chi-popover>

Use the classes chi-popover--top, chi-popover--right, chi-popover--bottom and chi-popover--left to position the arrow in the proper place. If you use a position engine such as Popper.js (used by Chi), the attribute x-placement should be used instead of these classes. It accepts all the values Popper.js does. Popper.js sets this attribute automatically, so there is no need to include it on the code.

<!-- Top -->
<section class="chi-popover chi-popover--top -active" aria-label="Popover Title" aria-modal="true" role="dialog">
  <div class="chi-popover__content">
    <p class="chi-popover__text">Popover content</p>
  </div>
  <div class="chi-popover__arrow"></div>
</section>

<!-- Right -->
<section class="chi-popover chi-popover--right -active" aria-label="Popover Title" aria-modal="true" role="dialog">
  <div class="chi-popover__content">
    <p class="chi-popover__text">Popover content</p>
  </div>
  <div class="chi-popover__arrow"></div>
</section>

<!-- Bottom -->
<section class="chi-popover chi-popover--bottom -active" aria-label="Popover Title" aria-modal="true" role="dialog">
  <div class="chi-popover__content">
    <p class="chi-popover__text">Popover content</p>
  </div>
  <div class="chi-popover__arrow"></div>
</section>

<!-- Left -->
<section class="chi-popover chi-popover--left -active" aria-label="Popover Title" aria-modal="true" role="dialog">
  <div class="chi-popover__content">
    <p class="chi-popover__text">Popover content</p>
  </div>
  <div class="chi-popover__arrow"></div>
</section>

Reference element

A reference element can be setup for advanced positioning. The popover will be positioned relative to this element.

Click me!

Web Component
HTML Blueprint

Use the reference attribute with a CSS selector to properly reference an element.

<chi-button id="example-3-button">Click me!</chi-button>

<!-- put the following code anywere in the DOM, e.g. at the end of the DOM -->
<chi-popover id="example-3-popover" position="top" title="Popover title" variant="text" arrow reference="#example-3-button" position="top" active></chi-popover>

<script>
  document.querySelector("#example-3-button")
    .addEventListener("click", function() {
      var popoverElem = document.querySelector("#example-3-popover");
      popoverElem.toggle();
    });
</script>

This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

<!-- Method 1 - Data Target -->
<button class="chi-button" id="popover-1b" data-target="#popover-in-html">Popover</button>
<!-- Put the following code anywere in the DOM, e.g. at the end of the DOM -->
<section class="chi-popover" id="popover-in-html" aria-modal="true" role="dialog" aria-label="Popover title">
  <header class="chi-popover__header">
    <h2 class="chi-popover__title">Popover title</h2>
  </header>
  <div class="chi-popover__content">
    <p class="chi-popover__text">Popover content</p>
  </div>
</section>
<script>chi.popover(document.getElementById('popover-1b'));</script>

<!-- Method 2 - Data Content -->
<button id='popover-1' class="chi-button" data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover title</h2></header><div class="chi-popover__content"><p class="chi-popover__text">Popover content</p></div>'>Popover</button>
<script>chi.popover(document.getElementById('popover-1'));</script>

Positioning

Further positions can be used in this mode: top, right, bottom, left, top-start, top-end, right-start, right-end, bottom-start, bottom-end, left-start, left-end.

Top start

Top

Top end

Left start

Left

Left end

Click buttons to see popover positions

Right start

Right

Right end

Bottom start

Bottom

Bottom end

Web Component
HTML Blueprint

<!-- Top -->
<chi-button id="example-4-t-button">Top popover</chi-button>
<chi-popover id="example-4-t-popover" position="top" title="Popover title" variant="text" arrow reference="#example-4-t-button">
  This popover is top positioned.
</chi-popover>

<!-- Top Start -->
<chi-button id="example-4-ts-button">Top start popover</chi-button>
<chi-popover id="example-4-ts-popover" position="top-start" title="Popover title" variant="text" arrow reference="#example-4-ts-button">
  This popover is top-start positioned.
</chi-popover>

<!-- Top End -->
<chi-button id="example-4-te-button">Top end popover</chi-button>
<chi-popover id="example-4-te-popover" position="top-end" title="Popover title" variant="text" arrow reference="#example-4-te-button">
  This popover is top-end positioned.
</chi-popover>

<!-- Right -->
<chi-button id="example-4-r-button">Right popover</chi-button>
<chi-popover id="example-4-r-popover" position="right" title="Popover title" variant="text" arrow reference="#example-4-r-button">
  This popover is right positioned.
</chi-popover>

<!-- Right Start -->
<chi-button id="example-4-rs-button">Right start popover</chi-button>
<chi-popover id="example-4-rs-popover" position="right-start" title="Popover title" variant="text" arrow reference="#example-4-rs-button">
  This popover is right-start positioned.
</chi-popover>

<!-- Right End -->
<chi-button id="example-4-re-button">Right end popover</chi-button>
<chi-popover id="example-4-re-popover" position="right-end" title="Popover title" variant="text" arrow reference="#example-4-re-button">
  This popover is right-end positioned.
</chi-popover>

<!-- Bottom -->
<chi-button id="example-4-b-button">Bottom popover</chi-button>
<chi-popover id="example-4-b-popover" position="bottom" title="Popover title" variant="text" arrow reference="#example-4-b-button">
  This popover is bottom positioned.
</chi-popover>

<!-- Bottom Start -->
<chi-button id="example-4-bs-button">Bottom start popover</chi-button>
<chi-popover id="example-4-bs-popover" position="bottom-start" title="Popover title" variant="text" arrow reference="#example-4-bs-button">
  This popover is bottom-start positioned.
</chi-popover>

<!-- Bottom End -->
<chi-button id="example-4-be-button">Bottom end popover</chi-button>
<chi-popover id="example-4-be-popover" position="bottom-end" title="Popover title" variant="text" arrow reference="#example-4-be-button">
  This popover is bottom-end positioned.
</chi-popover>

<!-- Left -->
<chi-button id="example-4-l-button">Left popover</chi-button>
<chi-popover id="example-4-l-popover" position="left" title="Popover title" variant="text" arrow reference="#example-4-l-button">
  This popover is left positioned.
</chi-popover>

<!-- Left Start -->
<chi-button id="example-4-ls-button">Left start popover</chi-button>
<chi-popover id="example-4-ls-popover" position="left-start" title="Popover title" variant="text" arrow reference="#example-4-ls-button">
  This popover is left-start positioned.
</chi-popover>

<!-- Left End -->
<chi-button id="example-4-le-button">Left end popover</chi-button>
<chi-popover id="example-4-le-popover" position="left-end" title="Popover title" variant="text" arrow reference="#example-4-le-button">
  This popover is left-end positioned.
</chi-popover>

This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

<!-- Top -->
<button data-position='top' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is top positioned.</p></div>' class="chi-button">Top popover</button>

<!-- Top Start -->
<button data-position='top-start' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is top start positioned.</p></div>' class="chi-button">Top start popover</button>

<!-- Top End -->
<button data-position='top-end' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is top end positioned.</p></div>' class="chi-button">Top end popover</button>

<!-- Right -->
<button class="chi-button" data-position='right' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is right positioned.</p></div>'>Right popover</button>

<!-- Right Start -->
<button class="chi-button" data-position='right-start' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is right start positioned.</p></div>'>Right start popover</button class="chi-button">

<!-- Right End -->
<button class="chi-button" data-position='right-end' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is right end positioned.</p></div>'>Right end popover</button class="chi-button">

<!-- Bottom -->
<button class="chi-button" data-position='bottom' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is bottom positioned.</p></div>'>Bottom popover</button>

<!-- Bottom Start -->
<button class="chi-button" data-position='bottom-start' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is bottom start positioned.</p></div>'>Bottom start popover</button class="chi-button">

<!-- Bottom End -->
<button class="chi-button" data-position='bottom-end' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is bottom end positioned.</p></div>'>Bottom end popover</button class="chi-button">

<!-- Left -->
<button class="chi-button" data-position='left' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is left positioned.</p></div>'>Left popover</button>

<!-- Left Start -->
<button class="chi-button" data-position='left-start' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is left start positioned.</p></div>'>Left start popover</button>

<!-- Left End -->
<button class="chi-button" data-position='left-end' data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover positioning</h2></header><div class="chi-popover__content"><p class="chi-popover__text">This popover is left end positioned.</p></div>'>Left end popover</button>

<!-- JavaScript -->
<script>chi.popover(document.querySelectorAll('[data-popover-content]'));</script>

Interaction

Read this handy introduction to HTML attributes and DOM properties.

Show

Hide

Toggle

Reference

Web Component
HTML Blueprint

Modify the active attribute or property to make the popover show or hide. The chi-popover element also has three public methods to interact with it: show(), hide(), toggle().

<chi-button id="example-5-button-show">Show</chi-button>
<chi-button id="example-5-button-hide">Hide</chi-button>
<chi-button id="example-5-button-toggle">Toggle</chi-button>
<chi-button id="example-5-button-reference">Reference</chi-button>

<chi-popover id="example-5-popover" position="top" title="Popover title" variant="text" arrow reference="#example-5-button-reference">
  Popover content
</chi-popover>

<script>
  var popover5 = document.getElementById('example-5-popover');

  var bShow = document.getElementById('example-5-button-show');
  bShow.addEventListener('click', function(){
    popover5.show();
    // or popover5.active = true;
  });

  var bHide = document.getElementById('example-5-button-hide');
  bHide.addEventListener('click', function () {
    popover5.hide();
    // or popover5.active = false;
  });

  var bToggle = document.getElementById('example-5-button-toggle');
  bToggle.addEventListener('click', function(){
    popover5.toggle();
    // or popover5.active = !popover5.active;
  });
</script>

This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

Use methods .show(), .hide(), and .toggle() to control popover visibility.

<button id='show-popover-3' class="chi-button">Show</button>
<button id='hide-popover-3' class="chi-button">Hide</button>
<button id='toggle-popover-3' class="chi-button">Toggle</button>
<button id='popover-3' class="chi-button" data-popover-content='<div class="chi-popover__content">Foo</div>'>Popover</button>
<script>
  var popover = chi.popover(
    document.getElementById('popover-3'),
    {
      trigger: 'manual',
      preventAutoHide: true
    }
  );
  document.getElementById('show-popover-3').addEventListener('click', function(e) {
    popover.show()
  });
  document.getElementById('hide-popover-3').addEventListener('click', function(e) {
    popover.hide()
  });
  document.getElementById('toggle-popover-3').addEventListener('click', function(e) {
    popover.toggle()
  });
</script>

Auto hide

Popovers automatically hide when clicking outside of it or when pressing the ESC key.

Auto hide

No auto hide

Web Component
HTML Blueprint

You can prevent automatic hiding behavior with the prevent-auto-hide attribute.

<!-- Auto hide -->
<chi-popover id="example-6-popover-auto-hide-popover" position="top" title="Popover title" variant="text" arrow reference="#example-6-auto-hide-button">
  Click outside. I will disappear!
</chi-popover>

<!-- No auto hide -->
<chi-popover id="example-6-popover-no-auto-hide-popover" position="top" title="Popover title" variant="text" arrow prevent-auto-hide reference="#example-6-no-auto-hide-button">
  Click outside. I will stay!
</chi-popover>

This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

You can prevent automatic hiding behavior by setting preventAutoHide to true

<!-- Auto hide -->
<button id='popover-6' class="chi-button" data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover title</h2></header><div class="chi-popover__content"><p class="chi-popover__text">Click outside. I will disappear!</p></div>'>Auto hide</button>
<script>chi.popover(document.getElementById('popover-6'),
  {
    preventAutoHide: false
  });
</script>

<!-- No auto hide -->
<button id='popover-6' class="chi-button" data-popover-content='<header class="chi-popover__header"><h2 class="chi-popover__title">Popover title</h2></header><div class="chi-popover__content"><p class="chi-popover__text">Click outside. I will stay!</p></div>'>No auto hide</button>
<script>chi.popover(document.getElementById('popover-6'),
  {
    preventAutoHide: true
  });
</script>

Popover with custom content

Popovers can be used to display any kind of custom content (even other components).

Are you sure you want to delete this?Delete

Cancel

Web Component
HTML Blueprint

Add buttons to Popovers by setting slot attribute to slot="chi-popover__footer".

<chi-popover position="top" title="Are you sure?" variant="text" active arrow>
  Are you sure you want to delete this?
  <chi-button slot="chi-popover__footer" color="danger">Delete</chi-button>
  <chi-button slot="chi-popover__footer">Cancel</chi-button>
</chi-popover>

Add buttons to Popovers by placing them in chi-popover__footer.

<section class="chi-popover chi-popover--top -active" aria-label="Are you sure?" aria-modal="true" role="dialog">
  <header class="chi-popover__header">
    <h2 class="chi-popover__title">Are you sure?</h2>
  </header>
  <div class="chi-popover__content">
    <p class="chi-popover__text">Are you sure you want to delete this?</p>
  </div>
  <div class="chi-popover__footer">
    <button class="chi-button -danger">Delete</button>
    <button class="chi-button">Cancel</button>
  </div>
  <div class="chi-popover__arrow"></div>
</section>

Web Component

Properties

Property	Attribute	Description	Type	Default
`active`	`active`	to open or close the popover	`boolean`	undefined
`arrow`	`arrow`	to add an arrow between the popover and the reference element	`boolean`	undefined
`position`	`position`	to set position of the popover { top, top-start, top-end, right, right-start, right-end, bottom, bottom-start, bottom-end, left, left-start, left-end }	`"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"`	`'top'`
`preventAutoHide`	`prevent-auto-hide`	Prevents closing the popover when clicking out of its bounds	`boolean`	undefined
`reference`	`reference`	CSS Selector to the reference Element. I.e. #id > p	`string`	undefined
`title`	`title`	to define popover title.	`string`	undefined
`variant`	`variant`	To define popover variant { text, custom }	`string`	undefined

Events

Event	Description	Type
`chiPopoverHidden`	Popover has been hidden to the user. The animation has completed.	`CustomEvent<any>`
`chiPopoverHide`	Popover hide method has executed, but the closing animation has not started yet	`CustomEvent<any>`
`chiPopoverShow`	Popover show method has executed, but the showing animation has not started yet	`CustomEvent<any>`
`chiPopoverShown`	Popover has been shown to the user and is fully visible. The animation has completed.	`CustomEvent<any>`

Methods

Method	Description	Returns	Parameters
`hide() => Promise<void>`	Hides the popover	Type: Promise<void>	-
`show() => Promise<void>`	Shows the popover.	Type: Promise<void>	-
`toggle() => Promise<void>`	Toggles active state (show/hide)	Type: Promise<void>	-

JavaScript

This component accepts options to configure its behavior.

Option	Default	Description
`animate`	`true`	Enables animation on popover display and hide.
`content`	`null`	Lets the developer include the popover content programmatically on the creation phase.
`position`	`'top'`	Where the popover will be located by default. If there is no free space in that position, the popover will try to flip the position to the opposite side. `data-position` takes precedence over this configuration option.
`arrow`	`true`	If set to true, an arrow will appear between the popover and the trigger element.
`parent`	`null`	If an element is provided as parent, the popover will be attached visually to that element. If not, the popover will be attached to the trigger used in instantiation.
`classes`	`[]`	Lets the developer add any classes to the popover element in the creation phase.
`trigger`	`'click'`	Available options are `click` or `manual`. Use click to attach the toggle action to the trigger element, and manual for develop a custom solution.
`target`	`'null'`	If you specify a target, the Popover will be build over that Element. You can specify the xpath selector of the element or the element itself.
`preventAutoHide`	`false`	Set `preventAutoHide` to `true` to prevent hidding the popover when clicking outside the popover.

Methods

.setContent()

Use this method to change the content of the popover. It discards any previously attached content, so any resources attached to the content should be removed to prevent memory leaks. This method accepts a string or an HTML DOM Element as a parameter.

<button id='popover-2' class="chi-button" data-popover-content='<div class="chi-popover__content">Foo</div>'>Popover</button>
<script>
  var popover = chi.popover(document.getElementById('popover-2'));
  popover.setContent('<div class="chi-popover__content">Bar</div>');
</script>

Events

Event	Description
`chi.popover.show`	The element the popover is attached to (usually a button), dispatches this event when the popover is to be shown.
`chi.popover.hide`	The element the popover is attached to (usually a button), dispatches this event when the popover is to be hidden.

Preventing memory leaks

Popover components have a dispose function to free all resources attached to the element, such as event listeners and object data. You must call this method when you want to remove the component.

var elem = document.getElementById('popover');
var popover = chi.popover(elem);
// do stuff
popover.dispose();

It is safe to call the popover method more than once, as it will return any previously created popover component associated to the trigger.

var elem = document.getElementById('popover-1');
var popover = chi.popover(elem);
var elem2 = document.getElementById('popover-1');
var popover2 = chi.popover(elem2);
popover === popover2; // returns true

popover.dispose(); // Only have to do it once.

Accessibility

Accessibility guidelines coming soon