ドキュメントを検索

Popover

設定やフィルターなど、ボタンの隣に開く小さなパネル。

popoverに対するWAI-ARIA APGパターンはありません。Popoverはボタンに紐づけられた非モーダルダイアログです。ページは引き続き操作可能で、ユーザーが移動するとポップオーバーは閉じます。

import { component$, useStyles$ } from '@builder.io/qwik';
import { Popover } from '@leve-ui/popover';
import { LuX } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Popover.Root class="popover-default">
      <Popover.Trigger class="popover-default-trigger">Dimensions</Popover.Trigger>
      <Popover.Content sideOffset={8} class="popover-default-content">
        <Popover.Title class="popover-default-title">Dimensions</Popover.Title>
        <Popover.Description class="popover-default-description">
          Set the size of the layer.
        </Popover.Description>
        <label class="popover-default-label">
          Width
          <input class="popover-default-input" name="width" value="320px" />
        </label>
        <label class="popover-default-label">
          Height
          <input class="popover-default-input" name="height" value="240px" />
        </label>
        <Popover.Close class="popover-default-close" aria-label="Close">
          <LuX class="popover-default-icon" aria-hidden="true" />
        </Popover.Close>
        {/* The library positions the arrow along the edge and sets data-side */}
        <Popover.Arrow class="popover-default-arrow" />
      </Popover.Content>
    </Popover.Root>
  );
});

インストール#

個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。

pnpm add @leve-ui/popover

構造#

import { Popover } from '@leve-ui/popover'; // or '@leve-ui/core'

<Popover.Root>
  <Popover.Anchor /> {/* optional */}
  <Popover.Trigger />
  <Popover.Content>
    <Popover.Title />
    <Popover.Description />
    <Popover.Close />
    <Popover.Arrow />
  </Popover.Content>
</Popover.Root>
パーツ要素説明
Popover.Root<div>各パーツをラップし、開閉状態を保持します。
Popover.Trigger<button>popoverを開閉するボタンです。asを使用して別の要素またはコンポーネントを描画します。
Popover.Anchor<div>省略可能。Triggerの代わりにpopoverを隣に配置する要素です。asを使用して別の要素またはコンポーネントを描画します。
Popover.Content<div>トップレイヤー内のpopover="manual"要素であるパネル。
Popover.Arrow<div>任意。CSSで描画される、Triggerを指す矢印。
Popover.Title<h2>ポップオーバーの名前を示すタイトル。
Popover.Description<p>ポップオーバーの説明。
Popover.Close<button>popoverを閉じるボタンです。asを使用して別の要素またはコンポーネントを描画します。

Popover.Trigger、Popover.Anchor、またはPopover.Closeのasに渡されるコンポーネントは、id、aria-*、data-*、およびon*$イベントハンドラーを含む受け取ったpropsを単一の要素に展開する必要があります。

Popover.Contentは配置した場所にレンダリングされ、トップレイヤーに表示されるため、祖先要素のoverflow: hiddenやz-indexによって切り取られることはありません。Floating UIを使用してTriggerの隣に配置されます。Contentにside、align、およびオフセットを設定すると、ビューポート内に留まるように反転およびシフトします。

例#

Anchor#

Popover.AnchorはTrigger以外の要素の隣にポップオーバーを配置します。ここでは、フィルターが検索フィールド全体の下に開き、--leve-popover-anchor-widthによってフィールドと同じ幅になります。

APIリファレンス#

Root#

Propデフォルト型
ids–{ trigger?: string; anchor?: string; content?: string; title?: string; description?: string }

パーツの要素IDをオーバーライドします。

defaultOpenfalseboolean

ポップオーバーが初期状態で開いているかどうか(非制御)。ページの再開時に開きます。

bind:open–Signal<boolean>

開閉状態を保持するシグナル(制御)。

onOpenChange$–QRL<(open: boolean) => void>

ユーザーの操作によってPopoverが開閉したときに呼び出されます。

すべての<div>属性も受け入れます。

データ属性値
data-leve-popover常に存在
data-state"open" | "closed"

Trigger#

Propデフォルト型
as'button'keyof HTMLElementTagNameMap | Component<any>

<button>の代わりにレンダリングする要素またはコンポーネントです。コンポーネントは受け取ったpropsを1つの要素にスプレッドする必要があります。

すべての<button>属性も受け入れます。

データ属性値
data-leve-popover-trigger常に存在
data-state"open" | "closed"

Anchor#

Propデフォルト型
as'div'keyof HTMLElementTagNameMap | Component<any>

<div>の代わりにレンダリングする要素またはコンポーネントです。コンポーネントは受け取ったpropsを1つの要素にスプレッドする必要があります。

すべての<div>属性も受け入れます。

データ属性値
data-leve-popover-anchor常に存在

Content#

Propデフォルト型
side'bottom''top' | 'right' | 'bottom' | 'left'

ポップオーバーを配置するTrigger(またはAnchor)の側。スペースがない場合は反転します。

align'center''start' | 'center' | 'end'

その側に沿った配置方向。

sideOffset0number

Triggerからの距離(px)。

alignOffset0number

側に沿ったオフセット(px)。

avoidCollisionstrueboolean

ビューポート内に収まるようにポップオーバーを反転およびシフトするかどうか。

collisionPadding0number

衝突を防ぐ際のビューポート端からのパディング(px)。

arrowPadding0number

矢印とポップオーバーの角との間のパディング(px)。

closeOnEscapetrueboolean

Escapeでポップオーバーを閉じるかどうか。

closeOnOutsideClicktrueboolean

ポップオーバー外でのポインターダウンで閉じるかどうか。

すべての<div>属性も受け入れます。

データ属性値
data-leve-popover-content常に存在
data-state"open" | "closed"
data-side反転後の最終的な配置側:"top" | "right" | "bottom" | "left"
data-align"start" | "center" | "end"
CSS変数値
--leve-popover-anchor-widthTrigger(またはAnchor)の幅
--leve-popover-anchor-heightTrigger(またはAnchor)の高さ
--leve-popover-available-widthビューポートで利用可能な幅
--leve-popover-available-heightビューポートで利用可能な高さ

Contentが開いている間、その位置がTriggerに依存するため、インラインのposition、top、leftが設定されます。表示中は:popover-openに一致し、@starting-styleと組み合わせてアニメーションを適用できます。display(例えばflex)は:popover-openにのみ設定してください。Content自体に設定すると、閉じたポップオーバーに対するブラウザのdisplay: noneが上書きされてしまいます。

Arrow#

独自のpropはありません。 すべての<div>属性を受け入れます。

データ属性値
data-leve-popover-arrow常に存在
data-sideContentの最終的な配置側

Arrowには、Triggerに面する端に沿ったインラインオフセットが設定されます。CSS(回転させた正方形など)や内部のSVGで描画します。

タイトル#

独自のpropはありません。 すべての<h2>属性を受け入れます。

データ属性値
data-leve-popover-title常に存在

説明#

独自のpropはありません。 すべての<p>属性を受け入れます。

データ属性値
data-leve-popover-description常に存在

閉じる#

Propデフォルト型
as'button'keyof HTMLElementTagNameMap | Component<any>

<button>の代わりにレンダリングする要素またはコンポーネントです。コンポーネントは受け取ったpropsを1つの要素にスプレッドする必要があります。

すべての<button>属性も受け入れます。

データ属性値
data-leve-popover-close常に存在
data-state"open" | "closed"

アクセシビリティ#

  • Popover.Contentはrole="dialog"、Popover.Titleを指すaria-labelledby、およびPopover.Descriptionを指すaria-describedbyをレンダリングします。Titleがない場合は、aria-labelで名前を付けます。
  • Popover.Triggerは、aria-haspopup="dialog"、aria-expanded、およびContentを指すaria-controlsをレンダリングします。
  • ポップオーバーが開くと、フォーカスはその最初のフォーカス可能な要素(またはContent)に移動します。EscapeおよびPopover.Closeでポップオーバーが閉じ、フォーカスがTriggerに戻ります。
  • ポップオーバーの外側をクリックするか、Tabでフォーカスを外に出すとポップオーバーが閉じ、フォーカスはユーザーが移動した場所にとどまります。
  • Popover.Arrowはaria-hidden="true"によって支援技術から隠されます。

キーボード操作#

キー説明
Enter / SpaceTrigger上でポップオーバーを開閉します。
Tabポップオーバー内でフォーカスを移動します。ポップオーバーから離れるとポップオーバーが閉じます。
EscapecloseOnEscapeがfalseでない限り、ポップオーバーを閉じてフォーカスをTriggerに戻します。