- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
"use client";
import {
autoUpdate,
flip,
offset,
shift,
useFloating,
} from "@floating-ui/react-dom";
import * as React from "react";
import { createPortal } from "react-dom";
import { getTransition, parseMotion, useReducedMotion } from "@/lib/motion";
import { cn } from "@/lib/utils";
const defaultPopoverMotion = "150 cubic-bezier(0.16, 1, 0.3, 1)";
function useControllableState<T>({
prop,
defaultProp,
onChange,
}: {
prop: T | undefined;
defaultProp: T;
onChange?: (value: T) => void;
}): [T, (next: T | ((prev: T) => T)) => void] {
const [uncontrolled, setUncontrolled] = React.useState<T>(defaultProp);
const isControlled = prop !== undefined;
const value = isControlled ? prop : uncontrolled;
const onChangeRef = React.useRef(onChange);
onChangeRef.current = onChange;
const setValue = React.useCallback(
(next: T | ((prev: T) => T)) => {
const resolved =
typeof next === "function"
? (next as (prev: T) => T)(isControlled ? (prop as T) : uncontrolled)
: next;
if (!isControlled) {
setUncontrolled(resolved);
}
onChangeRef.current?.(resolved);
},
[isControlled, prop, uncontrolled]
);
return [value, setValue];
}
function setRef<T>(ref: React.Ref<T> | undefined, node: T | null) {
if (!ref) {
return;
}
if (typeof ref === "function") {
ref(node);
} else {
(ref as React.MutableRefObject<T | null>).current = node;
}
}
function useComposedRefs<T>(...refs: Array<React.Ref<T> | undefined>) {
const refsRef = React.useRef(refs);
refsRef.current = refs;
return React.useCallback((node: T | null) => {
for (const ref of refsRef.current) {
setRef(ref, node);
}
}, []);
}
function composeEventHandlers<E extends { defaultPrevented: boolean }>(
theirHandler: ((event: E) => void) | undefined,
ourHandler: (event: E) => void
) {
return (event: E) => {
theirHandler?.(event);
if (!event.defaultPrevented) {
ourHandler(event);
}
};
}
interface PopoverContextValue {
anchor: HTMLElement | null;
contentId: string;
descriptionId: string;
descriptionPresent: boolean;
onOpenChange: (open: boolean) => void;
onOpenToggle: () => void;
open: boolean;
setAnchor: (node: HTMLElement | null) => void;
setDescriptionCount: React.Dispatch<React.SetStateAction<number>>;
setTitleCount: React.Dispatch<React.SetStateAction<number>>;
titleId: string;
titlePresent: boolean;
}
const PopoverContext = React.createContext<PopoverContextValue | null>(null);
function usePopoverContext(component: string): PopoverContextValue {
const ctx = React.useContext(PopoverContext);
if (!ctx) {
throw new Error(`${component} must be used within Popover`);
}
return ctx;
}
export interface PopoverProps {
children?: React.ReactNode;
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
open?: boolean;
}
function Popover({
children,
open: openProp,
defaultOpen,
onOpenChange,
}: PopoverProps) {
const [anchor, setAnchor] = React.useState<HTMLElement | null>(null);
const [titleCount, setTitleCount] = React.useState(0);
const [descriptionCount, setDescriptionCount] = React.useState(0);
const [open, setOpen] = useControllableState({
defaultProp: defaultOpen ?? false,
onChange: onOpenChange,
prop: openProp,
});
const contentId = React.useId();
const titleId = React.useId();
const descriptionId = React.useId();
const context = React.useMemo<PopoverContextValue>(
() => ({
anchor,
contentId,
descriptionId,
descriptionPresent: descriptionCount > 0,
onOpenChange: setOpen,
onOpenToggle: () => setOpen((prev) => !prev),
open,
setAnchor,
setDescriptionCount,
setTitleCount,
titleId,
titlePresent: titleCount > 0,
}),
[
anchor,
contentId,
descriptionCount,
descriptionId,
open,
setOpen,
titleCount,
titleId,
]
);
return (
<PopoverContext.Provider value={context}>
{children}
</PopoverContext.Provider>
);
}
export type PopoverTriggerProps = Omit<
React.ButtonHTMLAttributes<HTMLButtonElement>,
"ref"
> & {
as?: React.ElementType;
ref?: React.Ref<HTMLButtonElement>;
} & Record<string, unknown>;
function PopoverTrigger({ as, onClick, ref, ...props }: PopoverTriggerProps) {
const { open, contentId, onOpenToggle, setAnchor } =
usePopoverContext("PopoverTrigger");
const composedRef = useComposedRefs<HTMLButtonElement>(
ref as React.Ref<HTMLButtonElement> | undefined,
setAnchor as unknown as React.Ref<HTMLButtonElement>
);
const Component = as ?? "button";
const finalProps: Record<string, unknown> = {
...props,
"aria-controls": open ? contentId : undefined,
"aria-expanded": open,
"aria-haspopup": "dialog",
"data-state": open ? "open" : "closed",
onClick: composeEventHandlers(onClick, onOpenToggle),
ref: composedRef,
};
if (!(as || "type" in props)) {
finalProps.type = "button";
}
return React.createElement(Component, finalProps);
}
function useDismissablePopover({
open,
contentRef,
anchor,
onDismiss,
}: {
open: boolean;
contentRef: React.RefObject<HTMLElement | null>;
anchor: HTMLElement | null;
onDismiss: () => void;
}) {
React.useEffect(() => {
if (!open) {
return;
}
const ownerDocument = contentRef.current?.ownerDocument ?? document;
let isPointerInsideReactTree = false;
const handlePointerDown = (event: PointerEvent) => {
if (event.target && !isPointerInsideReactTree) {
const target = event.target as Node;
if (contentRef.current?.contains(target)) {
isPointerInsideReactTree = false;
return;
}
if (anchor?.contains(target)) {
isPointerInsideReactTree = false;
return;
}
onDismiss();
}
isPointerInsideReactTree = false;
};
const handleKeyDown = (event: KeyboardEvent) => {
if (event.key !== "Escape") {
return;
}
if (event.isComposing || event.keyCode === 229) {
return;
}
event.preventDefault();
onDismiss();
};
ownerDocument.addEventListener("pointerdown", handlePointerDown);
ownerDocument.addEventListener("keydown", handleKeyDown, { capture: true });
return () => {
ownerDocument.removeEventListener("pointerdown", handlePointerDown);
ownerDocument.removeEventListener("keydown", handleKeyDown, {
capture: true,
});
};
}, [open, contentRef, anchor, onDismiss]);
}
export interface PopoverContentProps extends React.ComponentProps<"div"> {
align?: "start" | "center" | "end";
alignOffset?: number;
avoidCollisions?: boolean;
motion?: string;
side?: "top" | "right" | "bottom" | "left";
sideOffset?: number;
}
function PopoverContent({
align = "center",
alignOffset = 0,
avoidCollisions = true,
className,
motion,
side = "bottom",
sideOffset = 4,
style,
...props
}: PopoverContentProps) {
const {
anchor,
contentId,
descriptionId,
descriptionPresent,
onOpenChange,
open,
titleId,
titlePresent,
} = usePopoverContext("PopoverContent");
const contentRef = React.useRef<HTMLDivElement>(null);
const [present, setPresent] = React.useState(open);
const exitTimerRef = React.useRef<number | undefined>(undefined);
const { floatingStyles, isPositioned, placement, refs } = useFloating({
elements: { reference: anchor },
middleware: [
offset({ alignmentAxis: alignOffset, mainAxis: sideOffset }),
avoidCollisions && shift({ padding: 0 }),
avoidCollisions && flip(),
],
placement: `${side}${align === "center" ? "" : `-${align}`}` as never,
strategy: "fixed",
whileElementsMounted: autoUpdate,
});
const [entered, setEntered] = React.useState(false);
React.useEffect(() => {
if (!open) {
setEntered(false);
return;
}
if (!isPositioned) {
return;
}
let id2: number | undefined;
const id1 = requestAnimationFrame(() => {
id2 = requestAnimationFrame(() => setEntered(true));
});
return () => {
cancelAnimationFrame(id1);
if (id2 !== undefined) {
cancelAnimationFrame(id2);
}
};
}, [open, isPositioned]);
React.useEffect(
() => () => {
if (exitTimerRef.current !== undefined) {
window.clearTimeout(exitTimerRef.current);
}
},
[]
);
const reduce = useReducedMotion();
const motionValue = motion ?? defaultPopoverMotion;
const motionTransition =
reduce || motion === "off"
? "none"
: getTransition(parseMotion(motionValue));
React.useEffect(() => {
if (open) {
if (exitTimerRef.current !== undefined) {
window.clearTimeout(exitTimerRef.current);
exitTimerRef.current = undefined;
}
setPresent(true);
return;
}
if (!present) {
return;
}
const parsed = reduce || motion === "off" ? null : parseMotion(motionValue);
const duration = parsed && !parsed.disabled ? parsed.duration : 0;
exitTimerRef.current = window.setTimeout(() => {
setPresent(false);
exitTimerRef.current = undefined;
}, duration + 50);
}, [open, present, reduce, motion, motionValue]);
useDismissablePopover({
anchor,
contentRef,
onDismiss: () => onOpenChange(false),
open,
});
React.useEffect(() => {
if (!open) {
return;
}
const content = contentRef.current;
if (!content) {
return;
}
const previousFocus = document.activeElement as HTMLElement | null;
const focusable = content.querySelector<HTMLElement>(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
if (focusable) {
focusable.focus({ preventScroll: true });
}
return () => {
if (previousFocus?.focus) {
previousFocus.focus({ preventScroll: true });
}
};
}, [open]);
if (!present) {
return null;
}
const [placedSide, placedAlign = "center"] = placement.split("-");
const originBySide: Record<string, string> = {
bottom: "top center",
left: "center right",
right: "center left",
top: "bottom center",
};
const innerStyle: React.CSSProperties = {
opacity: entered ? 1 : 0,
transform: entered ? "scale(1)" : "scale(0.95)",
transformOrigin: originBySide[placedSide] ?? "center",
transition: motionTransition ?? "none",
...style,
};
const node = (
<div
data-popper-wrapper=""
ref={refs.setFloating}
style={{
...floatingStyles,
minWidth: "max-content",
transform: isPositioned
? floatingStyles.transform
: "translate(0, -200%)",
}}
>
<div
aria-describedby={descriptionPresent ? descriptionId : undefined}
aria-labelledby={titlePresent ? titleId : undefined}
data-align={placedAlign}
data-side={placedSide}
data-slot="popover-content"
data-state={open ? "open" : "closed"}
id={contentId}
ref={contentRef}
role="dialog"
style={innerStyle}
{...props}
className={cn(
"bg-popover text-popover-foreground z-50 w-72 rounded-md border p-4 shadow-md outline-none",
className
)}
/>
</div>
);
return createPortal(node, document.body);
}
function PopoverHeader({
className,
...props
}: React.HTMLAttributes<HTMLDivElement>) {
return <div className={cn("flex flex-col gap-1.5", className)} {...props} />;
}
function PopoverTitle({
className,
...props
}: React.HTMLAttributes<HTMLHeadingElement>) {
const { setTitleCount, titleId } = usePopoverContext("PopoverTitle");
React.useEffect(() => {
setTitleCount((count) => count + 1);
return () => setTitleCount((count) => count - 1);
}, [setTitleCount]);
return (
<h2
className={cn("leading-none font-medium", className)}
id={titleId}
{...props}
/>
);
}
function PopoverDescription({
className,
...props
}: React.HTMLAttributes<HTMLParagraphElement>) {
const { setDescriptionCount, descriptionId } =
usePopoverContext("PopoverDescription");
React.useEffect(() => {
setDescriptionCount((count) => count + 1);
return () => setDescriptionCount((count) => count - 1);
}, [setDescriptionCount]);
return (
<p
className={cn("text-muted-foreground text-sm", className)}
id={descriptionId}
{...props}
/>
);
}
export type PopoverCloseProps = Omit<
React.ButtonHTMLAttributes<HTMLButtonElement>,
"ref"
> & {
as?: React.ElementType;
ref?: React.Ref<HTMLButtonElement>;
} & Record<string, unknown>;
function PopoverClose({ as, onClick, ref, ...props }: PopoverCloseProps) {
const { onOpenChange } = usePopoverContext("PopoverClose");
const Component = as ?? "button";
const finalProps: Record<string, unknown> = {
...props,
onClick: composeEventHandlers(onClick, () => onOpenChange(false)),
ref,
};
if (!(as || "type" in props)) {
finalProps.type = "button";
}
return React.createElement(Component, finalProps);
}
export {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverHeader,
PopoverTitle,
PopoverTrigger,
};A floating panel anchored to a trigger. Opens on trigger click, closes on outside click or Escape. Position is resolved by Floating UI, so the panel flips and shifts automatically when it would overflow the viewport.
Installation
$ bunx --bun frakment add popover$ npx frakment add popover$ pnpm dlx frakment add popover$ yarn dlx frakment add popover
Install the following dependencies:
$ bun add @floating-ui/react-dom$ npm install @floating-ui/react-dom$ pnpm add @floating-ui/react-dom$ yarn add @floating-ui/react-dom
Copy and paste the following code into your project.
"use client";
import {
autoUpdate,
flip,
offset,
shift,
useFloating,
} from "@floating-ui/react-dom";
import * as React from "react";
import { createPortal } from "react-dom";
import { getTransition, parseMotion, useReducedMotion } from "@/lib/motion";
import { cn } from "@/lib/utils";
const defaultPopoverMotion = "150 cubic-bezier(0.16, 1, 0.3, 1)";
function useControllableState<T>({
prop,
defaultProp,
onChange,
}: {
prop: T | undefined;
defaultProp: T;
onChange?: (value: T) => void;
}): [T, (next: T | ((prev: T) => T)) => void] {
const [uncontrolled, setUncontrolled] = React.useState<T>(defaultProp);
const isControlled = prop !== undefined;
const value = isControlled ? prop : uncontrolled;
const onChangeRef = React.useRef(onChange);
onChangeRef.current = onChange;
const setValue = React.useCallback(
(next: T | ((prev: T) => T)) => {
const resolved =
typeof next === "function"
? (next as (prev: T) => T)(isControlled ? (prop as T) : uncontrolled)
: next;
if (!isControlled) {
setUncontrolled(resolved);
}
onChangeRef.current?.(resolved);
},
[isControlled, prop, uncontrolled]
);
return [value, setValue];
}
function setRef<T>(ref: React.Ref<T> | undefined, node: T | null) {
if (!ref) {
return;
}
if (typeof ref === "function") {
ref(node);
} else {
(ref as React.MutableRefObject<T | null>).current = node;
}
}
function useComposedRefs<T>(...refs: Array<React.Ref<T> | undefined>) {
const refsRef = React.useRef(refs);
refsRef.current = refs;
return React.useCallback((node: T | null) => {
for (const ref of refsRef.current) {
setRef(ref, node);
}
}, []);
}
function composeEventHandlers<E extends { defaultPrevented: boolean }>(
theirHandler: ((event: E) => void) | undefined,
ourHandler: (event: E) => void
) {
return (event: E) => {
theirHandler?.(event);
if (!event.defaultPrevented) {
ourHandler(event);
}
};
}
interface PopoverContextValue {
anchor: HTMLElement | null;
contentId: string;
descriptionId: string;
descriptionPresent: boolean;
onOpenChange: (open: boolean) => void;
onOpenToggle: () => void;
open: boolean;
setAnchor: (node: HTMLElement | null) => void;
setDescriptionCount: React.Dispatch<React.SetStateAction<number>>;
setTitleCount: React.Dispatch<React.SetStateAction<number>>;
titleId: string;
titlePresent: boolean;
}
const PopoverContext = React.createContext<PopoverContextValue | null>(null);
function usePopoverContext(component: string): PopoverContextValue {
const ctx = React.useContext(PopoverContext);
if (!ctx) {
throw new Error(`${component} must be used within Popover`);
}
return ctx;
}
export interface PopoverProps {
children?: React.ReactNode;
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
open?: boolean;
}
function Popover({
children,
open: openProp,
defaultOpen,
onOpenChange,
}: PopoverProps) {
const [anchor, setAnchor] = React.useState<HTMLElement | null>(null);
const [titleCount, setTitleCount] = React.useState(0);
const [descriptionCount, setDescriptionCount] = React.useState(0);
const [open, setOpen] = useControllableState({
defaultProp: defaultOpen ?? false,
onChange: onOpenChange,
prop: openProp,
});
const contentId = React.useId();
const titleId = React.useId();
const descriptionId = React.useId();
const context = React.useMemo<PopoverContextValue>(
() => ({
anchor,
contentId,
descriptionId,
descriptionPresent: descriptionCount > 0,
onOpenChange: setOpen,
onOpenToggle: () => setOpen((prev) => !prev),
open,
setAnchor,
setDescriptionCount,
setTitleCount,
titleId,
titlePresent: titleCount > 0,
}),
[
anchor,
contentId,
descriptionCount,
descriptionId,
open,
setOpen,
titleCount,
titleId,
]
);
return (
<PopoverContext.Provider value={context}>
{children}
</PopoverContext.Provider>
);
}
export type PopoverTriggerProps = Omit<
React.ButtonHTMLAttributes<HTMLButtonElement>,
"ref"
> & {
as?: React.ElementType;
ref?: React.Ref<HTMLButtonElement>;
} & Record<string, unknown>;
function PopoverTrigger({ as, onClick, ref, ...props }: PopoverTriggerProps) {
const { open, contentId, onOpenToggle, setAnchor } =
usePopoverContext("PopoverTrigger");
const composedRef = useComposedRefs<HTMLButtonElement>(
ref as React.Ref<HTMLButtonElement> | undefined,
setAnchor as unknown as React.Ref<HTMLButtonElement>
);
const Component = as ?? "button";
const finalProps: Record<string, unknown> = {
...props,
"aria-controls": open ? contentId : undefined,
"aria-expanded": open,
"aria-haspopup": "dialog",
"data-state": open ? "open" : "closed",
onClick: composeEventHandlers(onClick, onOpenToggle),
ref: composedRef,
};
if (!(as || "type" in props)) {
finalProps.type = "button";
}
return React.createElement(Component, finalProps);
}
function useDismissablePopover({
open,
contentRef,
anchor,
onDismiss,
}: {
open: boolean;
contentRef: React.RefObject<HTMLElement | null>;
anchor: HTMLElement | null;
onDismiss: () => void;
}) {
React.useEffect(() => {
if (!open) {
return;
}
const ownerDocument = contentRef.current?.ownerDocument ?? document;
let isPointerInsideReactTree = false;
const handlePointerDown = (event: PointerEvent) => {
if (event.target && !isPointerInsideReactTree) {
const target = event.target as Node;
if (contentRef.current?.contains(target)) {
isPointerInsideReactTree = false;
return;
}
if (anchor?.contains(target)) {
isPointerInsideReactTree = false;
return;
}
onDismiss();
}
isPointerInsideReactTree = false;
};
const handleKeyDown = (event: KeyboardEvent) => {
if (event.key !== "Escape") {
return;
}
if (event.isComposing || event.keyCode === 229) {
return;
}
event.preventDefault();
onDismiss();
};
ownerDocument.addEventListener("pointerdown", handlePointerDown);
ownerDocument.addEventListener("keydown", handleKeyDown, { capture: true });
return () => {
ownerDocument.removeEventListener("pointerdown", handlePointerDown);
ownerDocument.removeEventListener("keydown", handleKeyDown, {
capture: true,
});
};
}, [open, contentRef, anchor, onDismiss]);
}
export interface PopoverContentProps extends React.ComponentProps<"div"> {
align?: "start" | "center" | "end";
alignOffset?: number;
avoidCollisions?: boolean;
motion?: string;
side?: "top" | "right" | "bottom" | "left";
sideOffset?: number;
}
function PopoverContent({
align = "center",
alignOffset = 0,
avoidCollisions = true,
className,
motion,
side = "bottom",
sideOffset = 4,
style,
...props
}: PopoverContentProps) {
const {
anchor,
contentId,
descriptionId,
descriptionPresent,
onOpenChange,
open,
titleId,
titlePresent,
} = usePopoverContext("PopoverContent");
const contentRef = React.useRef<HTMLDivElement>(null);
const [present, setPresent] = React.useState(open);
const exitTimerRef = React.useRef<number | undefined>(undefined);
const { floatingStyles, isPositioned, placement, refs } = useFloating({
elements: { reference: anchor },
middleware: [
offset({ alignmentAxis: alignOffset, mainAxis: sideOffset }),
avoidCollisions && shift({ padding: 0 }),
avoidCollisions && flip(),
],
placement: `${side}${align === "center" ? "" : `-${align}`}` as never,
strategy: "fixed",
whileElementsMounted: autoUpdate,
});
const [entered, setEntered] = React.useState(false);
React.useEffect(() => {
if (!open) {
setEntered(false);
return;
}
if (!isPositioned) {
return;
}
let id2: number | undefined;
const id1 = requestAnimationFrame(() => {
id2 = requestAnimationFrame(() => setEntered(true));
});
return () => {
cancelAnimationFrame(id1);
if (id2 !== undefined) {
cancelAnimationFrame(id2);
}
};
}, [open, isPositioned]);
React.useEffect(
() => () => {
if (exitTimerRef.current !== undefined) {
window.clearTimeout(exitTimerRef.current);
}
},
[]
);
const reduce = useReducedMotion();
const motionValue = motion ?? defaultPopoverMotion;
const motionTransition =
reduce || motion === "off"
? "none"
: getTransition(parseMotion(motionValue));
React.useEffect(() => {
if (open) {
if (exitTimerRef.current !== undefined) {
window.clearTimeout(exitTimerRef.current);
exitTimerRef.current = undefined;
}
setPresent(true);
return;
}
if (!present) {
return;
}
const parsed = reduce || motion === "off" ? null : parseMotion(motionValue);
const duration = parsed && !parsed.disabled ? parsed.duration : 0;
exitTimerRef.current = window.setTimeout(() => {
setPresent(false);
exitTimerRef.current = undefined;
}, duration + 50);
}, [open, present, reduce, motion, motionValue]);
useDismissablePopover({
anchor,
contentRef,
onDismiss: () => onOpenChange(false),
open,
});
React.useEffect(() => {
if (!open) {
return;
}
const content = contentRef.current;
if (!content) {
return;
}
const previousFocus = document.activeElement as HTMLElement | null;
const focusable = content.querySelector<HTMLElement>(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
if (focusable) {
focusable.focus({ preventScroll: true });
}
return () => {
if (previousFocus?.focus) {
previousFocus.focus({ preventScroll: true });
}
};
}, [open]);
if (!present) {
return null;
}
const [placedSide, placedAlign = "center"] = placement.split("-");
const originBySide: Record<string, string> = {
bottom: "top center",
left: "center right",
right: "center left",
top: "bottom center",
};
const innerStyle: React.CSSProperties = {
opacity: entered ? 1 : 0,
transform: entered ? "scale(1)" : "scale(0.95)",
transformOrigin: originBySide[placedSide] ?? "center",
transition: motionTransition ?? "none",
...style,
};
const node = (
<div
data-popper-wrapper=""
ref={refs.setFloating}
style={{
...floatingStyles,
minWidth: "max-content",
transform: isPositioned
? floatingStyles.transform
: "translate(0, -200%)",
}}
>
<div
aria-describedby={descriptionPresent ? descriptionId : undefined}
aria-labelledby={titlePresent ? titleId : undefined}
data-align={placedAlign}
data-side={placedSide}
data-slot="popover-content"
data-state={open ? "open" : "closed"}
id={contentId}
ref={contentRef}
role="dialog"
style={innerStyle}
{...props}
className={cn(
"bg-popover text-popover-foreground z-50 w-72 rounded-md border p-4 shadow-md outline-none",
className
)}
/>
</div>
);
return createPortal(node, document.body);
}
function PopoverHeader({
className,
...props
}: React.HTMLAttributes<HTMLDivElement>) {
return <div className={cn("flex flex-col gap-1.5", className)} {...props} />;
}
function PopoverTitle({
className,
...props
}: React.HTMLAttributes<HTMLHeadingElement>) {
const { setTitleCount, titleId } = usePopoverContext("PopoverTitle");
React.useEffect(() => {
setTitleCount((count) => count + 1);
return () => setTitleCount((count) => count - 1);
}, [setTitleCount]);
return (
<h2
className={cn("leading-none font-medium", className)}
id={titleId}
{...props}
/>
);
}
function PopoverDescription({
className,
...props
}: React.HTMLAttributes<HTMLParagraphElement>) {
const { setDescriptionCount, descriptionId } =
usePopoverContext("PopoverDescription");
React.useEffect(() => {
setDescriptionCount((count) => count + 1);
return () => setDescriptionCount((count) => count - 1);
}, [setDescriptionCount]);
return (
<p
className={cn("text-muted-foreground text-sm", className)}
id={descriptionId}
{...props}
/>
);
}
export type PopoverCloseProps = Omit<
React.ButtonHTMLAttributes<HTMLButtonElement>,
"ref"
> & {
as?: React.ElementType;
ref?: React.Ref<HTMLButtonElement>;
} & Record<string, unknown>;
function PopoverClose({ as, onClick, ref, ...props }: PopoverCloseProps) {
const { onOpenChange } = usePopoverContext("PopoverClose");
const Component = as ?? "button";
const finalProps: Record<string, unknown> = {
...props,
onClick: composeEventHandlers(onClick, () => onOpenChange(false)),
ref,
};
if (!(as || "type" in props)) {
finalProps.type = "button";
}
return React.createElement(Component, finalProps);
}
export {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverHeader,
PopoverTitle,
PopoverTrigger,
};Update the import paths to match your project setup.
Usage
import { Button } from "@/components/ui/button";
import {
Popover,
PopoverContent,
PopoverTrigger,
} from "@/components/ui/popover";<Popover>
<PopoverTrigger as={Button} variant="outline">Open</PopoverTrigger>
<PopoverContent>
Content
</PopoverContent>
</Popover>PopoverTrigger accepts as to render any component. Pass as={Button} for a styled trigger, or omit for a plain <button>.
Header and description
"use client";
import { Button } from "@/components/ui/button";
import {
Popover,
PopoverContent,
PopoverDescription,
PopoverHeader,
PopoverTitle,
PopoverTrigger,
} from "@/components/ui/popover";
export function PopoverBasic() {
return (
<Popover>
<PopoverTrigger as={Button} variant="outline">
Open Popover
</PopoverTrigger>
<PopoverContent align="start">
<PopoverHeader>
<PopoverTitle>Dimensions</PopoverTitle>
<PopoverDescription>
Set the dimensions for the layer.
</PopoverDescription>
</PopoverHeader>
</PopoverContent>
</Popover>
);
}PopoverHeader, PopoverTitle, and PopoverDescription wire aria-labelledby and aria-describedby onto the content automatically. Use them together so screen readers announce the panel correctly.
Alignments
"use client";
import { Button } from "@/components/ui/button";
import {
Popover,
PopoverContent,
PopoverTrigger,
} from "@/components/ui/popover";
export function PopoverAlignments() {
return (
<div className="flex gap-6">
<Popover>
<PopoverTrigger as={Button} size="sm" variant="outline">
Start
</PopoverTrigger>
<PopoverContent align="start" className="w-40">
Aligned to start
</PopoverContent>
</Popover>
<Popover>
<PopoverTrigger as={Button} size="sm" variant="outline">
Center
</PopoverTrigger>
<PopoverContent align="center" className="w-40">
Aligned to center
</PopoverContent>
</Popover>
<Popover>
<PopoverTrigger as={Button} size="sm" variant="outline">
End
</PopoverTrigger>
<PopoverContent align="end" className="w-40">
Aligned to end
</PopoverContent>
</Popover>
</div>
);
}Pass align to control horizontal placement: start, center (default), or end. Pass side for top, right, bottom (default), or left.
Form
"use client";
import { Button } from "@/components/ui/button";
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverHeader,
PopoverTitle,
PopoverTrigger,
} from "@/components/ui/popover";
export function PopoverForm() {
return (
<Popover>
<PopoverTrigger as={Button} variant="outline">
Open Popover
</PopoverTrigger>
<PopoverContent align="start" className="w-64">
<PopoverHeader>
<PopoverTitle>Dimensions</PopoverTitle>
<PopoverDescription>
Set the dimensions for the layer.
</PopoverDescription>
</PopoverHeader>
<FieldGroup className="gap-4">
<Field orientation="horizontal">
<FieldLabel className="w-1/2" htmlFor="form-width">
Width
</FieldLabel>
<Input defaultValue="100%" id="form-width" />
</Field>
<Field orientation="horizontal">
<FieldLabel className="w-1/2" htmlFor="form-height">
Height
</FieldLabel>
<Input defaultValue="25px" id="form-height" />
</Field>
</FieldGroup>
<div className="mt-4 flex justify-end gap-2">
<PopoverClose as={Button} size="sm" variant="ghost">
Cancel
</PopoverClose>
<Button size="sm">Save</Button>
</div>
</PopoverContent>
</Popover>
);
}Popover panels are not modal. They close on outside click, return focus to the trigger, and do not trap focus. For a focus-trapped experience, use Dialog.
API Reference
Popover
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | — | Controlled open state. When omitted, the popover manages its own state. |
defaultOpen | boolean | false | Uncontrolled initial open state. |
onOpenChange | (open: boolean) => void | — | Called when the popover opens or closes. |
PopoverTrigger
| Prop | Type | Default | Description |
|---|---|---|---|
as | React.ElementType | — | Renders a different root element or component. Defaults to button. |
className | string | — | Additional CSS classes. |
PopoverHeader
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | — | Additional CSS classes. Applies to the wrapper div (flex column, gap-1.5). |
PopoverTitle
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | — | Additional CSS classes. Renders an h2 with leading-none and font-medium by default. |
PopoverDescription
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | — | Additional CSS classes. Renders a p with text-muted-foreground and text-sm by default. |
PopoverContent
| Prop | Type | Default | Description |
|---|---|---|---|
side | toprightbottomleft | bottom | Placement relative to the trigger. |
align | startcenterend | center | Alignment along the cross axis. |
sideOffset | number | 4 | Gap between trigger and content in pixels. |
alignOffset | number | 0 | Shift along the cross axis in pixels. |
avoidCollisions | boolean | true | Flip and shift to stay inside the viewport. |
motion | string | — | Motion string for the entrance reveal. Pass off to disable. |
className | string | — | Additional CSS classes. |
PopoverClose
| Prop | Type | Default | Description |
|---|---|---|---|
as | React.ElementType | — | Renders a different root element or component. Defaults to button. |
Motion
The panel fades and scales in through Frakment's motion engine. Pass motion on PopoverContent:
<PopoverContent motion="200 ease-out">Content</PopoverContent>motion accepts "off", "150", "150 ease-out", or "150 cubic-bezier(0.4, 0, 0.2, 1)". The default is a 150ms smooth-out curve. prefers-reduced-motion wins and the panel appears instantly.
Accessibility
PopoverTriggersetsaria-haspopup="dialog",aria-expanded, andaria-controlson the trigger.PopoverTitleandPopoverDescriptionwirearia-labelledbyandaria-describedbyon the content when present.Escapecloses the popover. Outside click closes the popover.- Focus moves into the panel on open and returns to the trigger on close. Focus is not trapped.
Best Practices
- Pair a title with a description when the panel shows form fields or structured content.
- Use
align="start"for panels that should align with the trigger's leading edge, common in toolbars. - Keep content short. Popover is not a modal. Long forms belong in
Dialog.
Related Components
- Button: the default trigger
- Dialog: modal alternative with focus trap
- Dropdown Menu: menu alternative with keyboard navigation