Popover Arrow

Apply the popoverArrow patch to a floating popover container to add a small rotated arrow (rendered via ::after) that points toward the anchor element. Pass placement matching the popover's floating placement — the arrow is automatically drawn on the opposite side. Use color to match the popover surface and bordered to control whether the arrow has a 1 px border. Use sideOffset (a CSS length string, default themeSpacing(6)) to adjust how far the arrow is offset toward the start or end edge.

Props

Prop	Type	Default	Description
`placement`	`ValueOrState<Placement>`	`"bottom-end"`	Floating placement the popover sits at. The arrow is drawn on the opposite (flipped) side.
`sideOffset`	`string`	`themeSpacing(6)`	CSS length used to offset the arrow toward the start or end edge.
`color`	`ThemeColor`	`"neutral"`	Theme color tone for the arrow fill and border.
`bordered`	`boolean`	`true`	Whether the arrow draws a 1 px border.

Customization

Must see the source of patch at the bottom of each patch page to understand the structure then code it still code as html native element.

There are four levels of customization, in increasing order of effort:

Patch props. Each patch exposes a small, stable set of props—typically fewer than five. Lowest friction.
Context attributes. Use dataTone, dataSize, and dataDensity on a container to shift tone, size, or density for an entire subtree without touching individual elements.
Inline override. Native-wins merge strategy: any property set directly on the element overrides the patch value.
Create a variant. Clone a similar patch and edit it. Use this only when you need a reusable custom version.

Formulas

Unit - U = fontSize / 4 - convert final values with themeSpacing(n).

Size - n = intrinsic text lines, w = wrapping level, d = density factor:

height        = (n * 6 + 2 * d * w) * U
paddingBlock  = d * w * U
paddingInline = ceil(3 / w) * d * w * U
radius        = d * w * U

Base density d = 1.5:

U	w=0	w=1	w=2	w=3
height (`n = 1`)	6	9	12	15
paddingBlock	0	1.5	3	4.5
paddingInline	3	4.5	6	4.5
radius	0	1.5	3	4.5

Tone - K = N / 2 where N is the palette length. For N = 18, K = 9.

Role	Shift	n=0
Background	parent +/- n	0
Text	bg + K	6
Border	bg + K/2	3
Hover	bg + 2K/3	4
Selected / Focus	above +/- K/3	2-4

State shift range: K/3 <= delta <= 2K/3.

popoverArrow

import { type PartialElement, toState, type ValueOrState } from "@domphy/core";
import type { Placement } from "@domphy/floating";
import {
  type ThemeColor,
  themeColor,
  themeSize,
  themeSpacing,
} from "@domphy/theme";

/**
 * Renders a small rotated arrow (via a `::after` pseudo-element) that points from a
 * popover/tooltip toward its anchor, positioned and oriented based on the floating placement.
 * The arrow direction is computed by flipping the given placement. No host-tag check is
 * performed; apply it to the popover container element.
 *
 * @param props.placement - Floating placement the popover sits at; the arrow is drawn on the
 *   opposite (flipped) side. Accepts a value or reactive state. Defaults to `"bottom-end"`.
 *   One of: `top` | `bottom` | `left` | `right` | `top-start` | `top-end` | `bottom-start` |
 *   `bottom-end` | `left-start` | `left-end` | `right-start` | `right-end`.
 * @param props.sideOffset - CSS length used to offset the arrow toward the start/end edge.
 *   Defaults to `themeSpacing(6)`.
 * @param props.color - Theme color tone for the arrow fill and border. Defaults to `"neutral"`.
 * @param props.bordered - Whether the arrow draws a 1px border (set to `0px` when false).
 *   Defaults to `true`.
 * @example { div: [...], $: [popoverArrow({ placement: "top" })] }
 */
function popoverArrow(
  props: {
    placement?: ValueOrState<Placement>;
    sideOffset?: string;
    color?: ThemeColor;
    bordered?: boolean;
  } = {},
): PartialElement {
  const {
    placement = "bottom-end",
    color = "neutral",
    sideOffset = themeSpacing(6),
    bordered = true,
  } = props;

  const place = toState(placement);

  const flipMap: Record<Placement, Placement> = {
    top: "bottom",
    bottom: "top",
    left: "right",
    right: "left",
    "top-start": "bottom-end",
    "top-end": "bottom-start",
    "bottom-start": "top-end",
    "bottom-end": "top-start",
    "left-start": "right-end",
    "left-end": "right-start",
    "right-start": "left-end",
    "right-end": "left-start",
  };

  const getFlipped = (listener: any) =>
    flipMap[place.get(listener)] ?? flipMap["bottom-end"];
  const start = (pos: string) =>
    pos.includes("start") ? sideOffset : pos.includes("end") ? "auto" : "50%";
  const end = (pos: string) =>
    pos.includes("end") ? sideOffset : pos.includes("start") ? "auto" : "50%";

  return {
    style: {
      fontSize: (listener) => themeSize(listener),
      backgroundColor: (listener) => themeColor(listener),
      color: (listener) => themeColor(listener, "text", color),
      position: "relative",
      "&::after": {
        content: `""`,
        position: "absolute",
        width: themeSpacing(1.5),
        height: themeSpacing(1.5),
        backgroundColor: (listener) => themeColor(listener, "inherit", color),
        borderWidth: bordered ? "1px" : 0,
        borderColor: (listener) => themeColor(listener, "border-strong", color),
        borderTopStyle: (listener) => {
          const pos = getFlipped(listener);

          return pos.includes("top") || pos.includes("right")
            ? `solid`
            : "none";
        },
        borderBottomStyle: (listener) => {
          const pos = getFlipped(listener);

          return pos.includes("bottom") || pos.includes("left")
            ? `solid`
            : "none";
        },
        borderLeftStyle: (listener) => {
          const pos = getFlipped(listener);
          return pos.includes("top") || pos.includes("left") ? `solid` : "none";
        },
        borderRightStyle: (listener) => {
          const pos = getFlipped(listener);
          return pos.includes("bottom") || pos.includes("right")
            ? `solid`
            : "none";
        },
        top: (listener) => {
          const pos = getFlipped(listener);
          return pos.includes("top")
            ? 0
            : pos.includes("bottom")
              ? "auto"
              : start(pos);
        },
        right: (listener) => {
          const pos = getFlipped(listener);
          return pos.includes("right")
            ? 0
            : pos.includes("left")
              ? "auto"
              : end(pos);
        },
        bottom: (listener) => {
          const pos = getFlipped(listener);
          return pos.includes("bottom")
            ? 0
            : pos.includes("top")
              ? "auto"
              : end(pos);
        },
        left: (listener) => {
          const pos = getFlipped(listener);
          return pos.includes("left")
            ? 0
            : pos.includes("right")
              ? "auto"
              : start(pos);
        },
        transform: (listener) => {
          const pos = getFlipped(listener);
          const x =
            pos.includes("right") ||
            (pos.includes("end") && !pos.includes("left"))
              ? "50%"
              : "-50%";
          const y =
            pos.includes("bottom") ||
            (pos.includes("end") && !pos.includes("top"))
              ? "50%"
              : "-50%";
          return `translate(${x},${y}) rotate(45deg)`;
        },
      },
    },
  };
}

export { popoverArrow };

Popover Arrow#

Props#

Props