Skip to content
WebJs
Menu

Displays rich content in a popup, triggered by a button.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { inputClass } from '#components/ui/input.ts';
import { labelClass } from '#components/ui/label.ts';
import { popoverContentClass } from '#components/ui/popover.ts';

const field = (id: string, label: string, value: string) => html`
  <div class="grid grid-cols-3 items-center gap-4">
    <label data-slot="label" for=${id} class=${labelClass()}>${label}</label>
    <input data-slot="input" id=${id} value=${value} class=${cn(inputClass(), 'col-span-2 h-8')}>
  </div>
`;

export default function PopoverDemo() {
  return html`
    <button type="button" popovertarget="popover-demo" aria-haspopup="dialog" aria-expanded="false" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Open popover</button>
    <div id="popover-demo" popover role="dialog" aria-labelledby="popover-demo-title" data-slot="popover-content" data-side="bottom" data-align="center" class=${cn(popoverContentClass(), 'w-80')}>
      <div class="grid gap-4">
        <div class="space-y-2">
          <h4 id="popover-demo-title" class="leading-none font-medium">Dimensions</h4>
          <p class="text-sm text-muted-foreground">
            Set the dimensions for the layer.
          </p>
        </div>
        <div class="grid gap-2">
          ${field('width', 'Width', '100%')}
          ${field('maxWidth', 'Max. width', '300px')}
          ${field('height', 'Height', '25px')}
          ${field('maxHeight', 'Max. height', 'none')}
        </div>
      </div>
    </div>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add popover

Usage

import { buttonClass } from '#components/ui/button.ts';
import {
  popoverContentClass,
  popoverDescriptionClass,
  popoverHeaderClass,
  popoverTitleClass,
} from '#components/ui/popover.ts';
<button
  popovertarget="popover"
  aria-haspopup="dialog"
  aria-expanded="false"
  class=${buttonClass({ variant: 'outline' })}
>
  Open Popover
</button>
<div
  id="popover"
  popover
  role="dialog"
  aria-labelledby="popover-title"
  class=${popoverContentClass()}
>
  <div class=${popoverHeaderClass()}>
    <h3 id="popover-title" class=${popoverTitleClass()}>Title</h3>
    <p class=${popoverDescriptionClass()}>Description text here.</p>
  </div>
</div>

Composition

Use the following composition to build a popover:

button popovertarget="id"
div popover id="id"          popoverContentClass()
└── div                      popoverHeaderClass()
    ├── h3                   popoverTitleClass()
    └── p                    popoverDescriptionClass()

The popover is the browser's own Popover API. The popovertarget button opens the panel, which renders in the top layer, closes on an outside click or Escape, returns focus to the button, and is anchored to the button by CSS Anchor Positioning, all with no script.

Basic

A simple popover with a header, title, and description.

import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import {
  popoverContentClass, popoverHeaderClass, popoverTitleClass, popoverDescriptionClass,
} from '#components/ui/popover.ts';

export default function PopoverBasic() {
  return html`
    <button type="button" popovertarget="popover-basic" aria-haspopup="dialog" aria-expanded="false" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Open Popover</button>
    <div id="popover-basic" popover role="dialog" aria-labelledby="popover-basic-title" aria-describedby="popover-basic-description" data-slot="popover-content" data-side="bottom" data-align="start" class=${popoverContentClass({ align: 'start' })}>
      <div data-slot="popover-header" class=${popoverHeaderClass()}>
        <h3 id="popover-basic-title" data-slot="popover-title" class=${popoverTitleClass()}>Dimensions</h3>
        <p id="popover-basic-description" data-slot="popover-description" class=${popoverDescriptionClass()}>
          Set the dimensions for the layer.
        </p>
      </div>
    </div>
  `;
}
View Code

Align

Use the align option of popoverContentClass() to control the horizontal alignment.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { popoverContentClass, type PopoverAlign } from '#components/ui/popover.ts';

const aligned = (align: PopoverAlign, label: string, text: string) => {
  const id = 'popover-align-' + align;
  return html`
    <button type="button" popovertarget=${id} aria-haspopup="dialog" aria-expanded="false" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>
      ${label}
    </button>
    <div id=${id} popover role="dialog" aria-label=${text} data-slot="popover-content" data-side="bottom" data-align=${align} class=${cn(popoverContentClass({ align }), 'w-40')}>
      ${text}
    </div>
  `;
};

export default function PopoverAlignments() {
  return html`
    <div class="flex gap-6">
      ${aligned('start', 'Start', 'Aligned to start')}
      ${aligned('center', 'Center', 'Aligned to center')}
      ${aligned('end', 'End', 'Aligned to end')}
    </div>
  `;
}
View Code

With Form

A popover with form fields inside.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { fieldGroupClass, fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';
import {
  popoverContentClass, popoverHeaderClass, popoverTitleClass, popoverDescriptionClass,
} from '#components/ui/popover.ts';

const field = (id: string, label: string, value: string) => html`
  <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
    <label data-slot="field-label" for=${id} class=${cn(fieldLabelClass(), 'w-1/2')}>${label}</label>
    <input data-slot="input" id=${id} value=${value} class=${inputClass()}>
  </div>
`;

export default function PopoverForm() {
  return html`
    <button type="button" popovertarget="popover-form" aria-haspopup="dialog" aria-expanded="false" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Open Popover</button>
    <div id="popover-form" popover role="dialog" aria-labelledby="popover-form-title" aria-describedby="popover-form-description" data-slot="popover-content" data-side="bottom" data-align="start" class=${cn(popoverContentClass({ align: 'start' }), 'w-64')}>
      <div data-slot="popover-header" class=${popoverHeaderClass()}>
        <h3 id="popover-form-title" data-slot="popover-title" class=${popoverTitleClass()}>Dimensions</h3>
        <p id="popover-form-description" data-slot="popover-description" class=${popoverDescriptionClass()}>
          Set the dimensions for the layer.
        </p>
      </div>
      <div data-slot="field-group" class=${cn(fieldGroupClass(), 'gap-4')}>
        ${field('popover-form-width', 'Width', '100%')}
        ${field('popover-form-height', 'Height', '25px')}
      </div>
    </div>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import {
  popoverContentClass, popoverHeaderClass, popoverTitleClass, popoverDescriptionClass,
  type PopoverSide,
} from '#components/ui/popover.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      title: 'Dimensions',
      description: 'Set the dimensions for the layer.',
      left: 'Left',
      top: 'Top',
      bottom: 'Bottom',
      right: 'Right',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      title: 'الأبعاد',
      description: 'تعيين الأبعاد للطبقة.',
      left: 'يسار',
      top: 'أعلى',
      bottom: 'أسفل',
      right: 'يمين',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      title: 'מימדים',
      description: 'הגדר את המימדים לשכבה.',
      left: 'שמאל',
      top: 'למעלה',
      bottom: 'למטה',
      right: 'ימין',
    },
  },
};

const physicalSides: PopoverSide[] = ['left', 'top', 'bottom', 'right'];

// The provider is the dir attribute on each panel, as in shadcn's demo.
export default function PopoverRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  const sidePopover = (side: PopoverSide) => {
    const id = 'popover-rtl-' + side;
    return html`
      <button type="button" popovertarget=${id} aria-haspopup="dialog" aria-expanded="false" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>${t[side]}</button>
      <div id=${id} popover role="dialog" dir=${dir} lang=${lang} aria-labelledby=${id + '-title'} data-slot="popover-content" data-side=${side} data-align="center" class=${popoverContentClass({ side })}>
        <div data-slot="popover-header" class=${popoverHeaderClass()}>
          <h3 id=${id + '-title'} data-slot="popover-title" class=${popoverTitleClass()}>${t.title}</h3>
          <p data-slot="popover-description" class=${popoverDescriptionClass()}>${t.description}</p>
        </div>
      </div>
    `;
  };

  return html`
    <div class="flex flex-wrap justify-center gap-2">
      ${physicalSides.map(sidePopover)}
    </div>
  `;
}
View Code

API Reference

popoverContentClass

popoverContentClass() returns the classes for the panel, a <div popover> opened by a button whose popovertarget names its id. Placement is CSS Anchor Positioning, so the options are a fixed set the stylesheet carries. For any other offset, set the margin inline.

OptionTypeDefault
side"top" | "right" | "bottom" | "left""bottom"
align"start" | "center" | "end""center"
sideOffset0 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 244
alignOffset0 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 240

Header, Title, Description

popoverHeaderClass(), popoverTitleClass() and popoverDescriptionClass() take no options. Make the title a real heading at the right level for its place in the page.

Accessibility

A class helper returns only classes, so the panel's role and name are yours to supply. Give the panel role="dialog" and name it with aria-labelledby pointing at the title, and aria-describedby pointing at the description when there is one. Give the button aria-haspopup="dialog" and an aria-expanded kept in sync from the panel's native toggle event.

const panel = document.getElementById('popover');
const trigger = document.querySelector('[popovertarget="popover"]');
panel.addEventListener('toggle', (e) => {
  trigger.setAttribute('aria-expanded', String(e.newState === 'open'));
});