basecoat/docs/src/components/popover.njk

---
layout: layouts/page.njk
title: Popover
description: Displays rich content in a portal, triggered by a button.
toc:
  - label: Usage
    id: usage
    children:
      - label: HTML + JavaScript
        id: usage-html-js
        children:
          - label: "Step 1 (Optional): Include the JavaScript file"
            id: usage-html-js-1
          - label: "Step 2: Add your popover HTML"
            id: usage-html-js-2
          - label: HTML structure
            id: usage-html-js-3
      - label: Jinja and Nunjucks
        id: usage-macro
---

{% from "macros/code_preview.njk" import code_preview %}
{% from "macros/code_block.njk" import code_block %}
{% from "popover.njk" import popover %}

{% set code_html %}
{% call popover(
  id="demo-popover",
  trigger="Open popover",
  trigger_attrs={"class": "btn-outline"},
  popover_attrs={"class": "w-80"}
) %}
  <div class="grid gap-4">
    <header class="grid gap-1.5">
      <h4 class="leading-none font-medium">Dimensions</h4>
      <p class="text-muted-foreground text-sm">Set the dimensions for the layer.</p>
    </header>
    <form class="form grid gap-2">
      <div class="grid grid-cols-3 items-center gap-4">
        <label for="demo-popover-width">Width</label>
        <input type="text" id="demo-popover-width" value="100%" class="col-span-2 h-8" autofocus/>
      </div>
      <div class="grid grid-cols-3 items-center gap-4">
        <label for="demo-popover-max-width">Max. width</label>
        <input type="text" id="demo-popover-max-width" value="300px" class="col-span-2 h-8"/>
      </div>
      <div class="grid grid-cols-3 items-center gap-4">
        <label for="demo-popover-height">Height</label>
        <input type="text" id="demo-popover-height" value="25px" class="col-span-2 h-8"/>
      </div>
      <div class="grid grid-cols-3 items-center gap-4">
        <label for="demo-popover-max-height">Max. height</label>
        <input type="text" id="demo-popover-max-height" value="none" class="col-span-2 h-8"/>
      </div>
    </form>
  </div>
{% endcall %}
{% endset %}

{{ code_preview("popover", code_html | prettyHtml) }}

<h2 id="usage"><a href="#usage">Usage</a></h2>

<h3 id="usage-html-js"><a href="#usage-html-js">HTML + JavaScript</a></h3>

<h4 id="usage-html-js-1"><a href="#usage-html-js-1">Step 1: Include the JavaScript file</a></h4>

<section class="prose">
  <p>You can either <a href="/installation/#install-cdn-all">include the JavaScript file for all the components</a>, or just the one for this component by adding this to the <code>&lt;head&gt;</code> of your page:</p>
</section>

{% set code_script %}<script src="https://cdn.jsdelivr.net/npm/basecoat-css@{{ site.version }}/dist/js/popover.min.js" defer></script>{% endset %}
{{ code_block(code_script | prettyHtml, "html") }}

<div class="flex flex-wrap gap-2 my-6">
  <a class="badge-outline" href="/installation/#install-js">
    Components with JavaScript
    {% lucide "arrow-right" %}
  </a>
  <a class="badge-outline" href="/installation/#install-cli">
    Use the CLI
    {% lucide "arrow-right" %}
  </a>
</div>

<h4 id="usage-html-js-2"><a href="#usage-html-js-2">Step 2: Add your popover HTML</a></h4>

{{ code_block(code_html | prettyHtml, "html") }}

<h4 id="usage-html-js-3"><a href="#usage-html-js-3">HTML structure</a></h4>

<section class="prose">
  <dl>
    <dt><code class="highlight language-html">&lt;button type="button" popovertarget="{ POPOVER_ID }"&gt;</code></dt>
    <dd>
      <p>The trigger to open the popover, can also have the following attributes:</p>
      <ul>
        <li><code>id="{BUTTON_ID}"</code>: linked to by the <code>aria-labelledby</code> attribute of the listbox.</li>
        <li><code>aria-expanded="false"</code>: tracks the popover's state.</li>
        <li><code>onclick</code>: a simple function to update <code>aria-expanded</code>.</li>
      </ul>
    </dd>
    <dt><code class="highlight language-html">&lt;div popover class="popover" id="{ POPOVER_ID }"&gt;</code></dt>
    <dd>As with the <a href="/components/popover">Popover</a> component, you can set up the side and alignment of the popover using the <code>data-side</code> and <code>data-align</code> attributes.</dd>
  </dl>
</section>

<h3 id="usage-macro"><a href="#usage-macro">Jinja and Nunjucks</a></h3>

<div class="prose">
  <p>You can use the <code class="relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-xs">popover()</code> Nunjucks or Jinja macro for this component.</p>
</div>

<div class="flex flex-wrap gap-2 my-6">
  <a class="badge-outline" href="/installation/#install-macros" target="_blank">
    Use Nunjucks or Jinja macros
    {% lucide "arrow-right" %}
  </a>
  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/jinja/popover.html.jinja" target="_blank">
    Jinja macro
    {% lucide "arrow-right" %}
  </a>
  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/nunjucks/popover.njk" target="_blank">
    Nunjucks macro
    {% lucide "arrow-right" %}
  </a>
</div>

{% set raw_code %}{% raw %}{% call popover(
  id="demo-popover",
  trigger="Open popover",
  trigger_attrs={"class": "btn-outline"},
  popover_attrs={"class": "w-80 p-4"}
) %}
  <div class="grid gap-4">
    <header class="grid gap-1.5">
      <h4 class="leading-none font-medium">Dimensions</h4>
      <p class="text-muted-foreground text-sm">Set the dimensions for the layer.</p>
    </header>
    <form class="form grid gap-2">
      <div class="grid grid-cols-3 items-center gap-4">
        <label for="demo-popover-width">Width</label>
        <input type="text" id="demo-popover-width" value="100%" class="col-span-2 h-8"/>
      </div>
      <div class="grid grid-cols-3 items-center gap-4">
        <label for="demo-popover-max-width">Max. width</label>
        <input type="text" id="demo-popover-max-width" value="300px" class="col-span-2 h-8"/>
      </div>
      <div class="grid grid-cols-3 items-center gap-4">
        <label for="demo-popover-height">Height</label>
        <input type="text" id="demo-popover-height" value="25px" class="col-span-2 h-8"/>
      </div>
      <div class="grid grid-cols-3 items-center gap-4">
        <label for="demo-popover-max-height">Max. height</label>
        <input type="text" id="demo-popover-max-height" value="none" class="col-span-2 h-8"/>
      </div>
    </form>
  </div>
{% endcall %}{% endraw %}{% endset %}
{{ code_block(raw_code, "jinja") }}