Overlay Components

Popup

A floating element anchored to a trigger element using CSS Anchor Positioning. Supports 12 placement options, width matching, and click-outside dismissal.

Basic Popup

A floating element anchored to a button. Closes on outside click or Escape.

Browser support: Popup uses the CSS Anchor Positioning API (Chrome 125+, Edge 125+). Other browsers may need a polyfill.

const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);

<Button ref={anchorRef} onClick={() => setOpen(!open)}>Toggle</Button>
<Popup open={open} onClose={() => setOpen(false)} anchorRef={anchorRef}>
  <Card>Popup content</Card>
</Popup>

Placement Options

Use the placement prop to position the popup. Supports top, bottom, left, right and their -start/-end variants (12 total). Default is bottom-start.

<Popup placement="top" anchorRef={ref} open={open} onClose={onClose}>
  <Card>Top placement</Card>
</Popup>

Match Anchor Width

Use matchWidth to make the popup match the width of its anchor element. Useful for select-like dropdowns.

<Popup matchWidth anchorRef={ref} open={open} onClose={onClose}>
  <Card>Same width as anchor</Card>
</Popup>

Popup with Rich Content

Popups can contain any content including cards, buttons, and other components.

<Popup anchorRef={ref} open={open} onClose={onClose}>
  <Card shadow>
    <Stack>
      <Text bold>User Menu</Text>
      <Button>Profile</Button>
      <Button danger>Sign Out</Button>
    </Stack>
  </Card>
</Popup>

PopupTrigger (Click)

PopupTrigger is a convenience wrapper that manages open/close state and ref wiring automatically. No need for useState or useRef — just wrap your trigger element and provide the popup content.

The default trigger mode is "click", which toggles the popup on click.

import { PopupTrigger, Button, Card, Text } from "@vaneui/ui";

<PopupTrigger popup={<Card sm shadow><Text sm>Click-triggered popup</Text></Card>}>
  <Button>Click Me</Button>
</PopupTrigger>

Set trigger="hover" to show the popup on mouse enter and hide it on mouse leave. Use openDelay to add a delay (in milliseconds) before the popup appears, and closeDelay (default: 150ms) before it disappears. This is useful for tooltip-like behavior.

<PopupTrigger
  trigger="hover"
  openDelay={200}
  popup={<Card sm shadow><Text sm>Tooltip text</Text></Card>}
>
  <Button>Hover Me</Button>
</PopupTrigger>

PopupTrigger (Focus)

Set trigger="focus" to show the popup when the trigger element receives focus and hide it on blur. Useful for search autocomplete, input hints, and accessible dropdown suggestions.

<PopupTrigger
  trigger="focus"
  popup={<Card sm shadow><Text sm>Search suggestions...</Text></Card>}
>
  <Input placeholder="Search..." />
</PopupTrigger>

Popup with Arrow

Use the arrow prop to display a small pointer/arrow on the popup that visually connects it to its anchor element. This is especially useful for tooltip-style popups where you want a clear visual link between the trigger and content.

const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);

<Button ref={anchorRef} onClick={() => setOpen(!open)}>Toggle Arrow Popup</Button>
<Popup open={open} onClose={() => setOpen(false)} anchorRef={anchorRef} arrow>
  <Card sm shadow>
    <Text sm>This popup has an arrow pointing to its anchor.</Text>
  </Card>
</Popup>

All 12 Placements

Popup supports 12 placement positions via boolean props: top, topStart, topEnd, bottom, bottomStart, bottomEnd, left, leftStart, leftEnd, right, rightStart, rightEnd. Each prop positions the popup relative to the anchor element.

{/* Position above, aligned to start */}
<Popup topStart anchorRef={ref} open={open} onClose={onClose}>
  <Card>Top Start</Card>
</Popup>

{/* Position to the right, centered */}
<Popup right anchorRef={ref} open={open} onClose={onClose}>
  <Card>Right</Card>
</Popup>

Advanced Props

Popup supports additional configuration props for fine-tuning behavior:

Prop	Default	Description
`offset`	`4`	Distance from anchor in pixels
`closeOnEscape`	`true`	Close on Escape key press
`closeOnClickOutside`	`true`	Close when clicking outside
`portal`	`true`	Render in a portal (document.body)
`keepMounted`	`false`	Keep DOM node when closed
`noAnimation`	`false`	Disable enter/exit transitions
`transitionDuration`	`200`	Animation duration in ms
`disabled`	`false`	Prevent popup from opening
`hideWhenDetached`	`false`	Hide when anchor scrolls out of view
`role`	`"dialog"`	ARIA role for accessibility

<Popup
  open={open}
  onClose={onClose}
  anchorRef={ref}
  offset={8}
  noAnimation
  closeOnEscape={false}
>
  <Card>Custom config</Card>
</Popup>

Popup Props

Font Weight

Font weight props for controlling text weight

thin

Thin font weight (100)

extralight

Extra light font weight (200)

light

Light font weight (300)

normal

Normal font weight (400)

medium

Medium font weight (500)

semibold

Semibold font weight (600)

bold

Bold font weight (700)

extrabold

Extra bold font weight (800)

black

Black font weight (900)

Font Style

Font style props for controlling text style

italic

Italic font style

notItalic

Not italic (normal) font style

Text Decoration

Text decoration props for controlling text underline/strikethrough

underline

Add underline decoration below text

lineThrough

Add strikethrough/line-through decoration across text

noUnderline

Remove text decoration (no underline, strikethrough, etc.)

overline

Add overline decoration above text

Text Transform

Text transform props for controlling text case

uppercase

Transform text to uppercase

lowercase

Transform text to lowercase

capitalize

Capitalize first letter of each word

normalCase

Normal text case (no transformation)

Font Family

Font family props for controlling text font

sans

Sans-serif font family (default)

serif

Serif font family

mono

Monospace font family

heading

Heading font family (defaults to sans, independently customizable via --font-heading CSS variable)

Text Align

Text alignment props for controlling text position

textLeft

Align text to left

textCenter

Align text to center

textRight

Align text to right

textJustify

Justify text

Truncate

Truncate props for controlling text overflow with ellipsis

truncate

Single line truncation with ellipsis

lineClamp2

Truncate at 2 lines with ellipsis

lineClamp3

Truncate at 3 lines with ellipsis

lineClamp4

Truncate at 4 lines with ellipsis

lineClamp5

Truncate at 5 lines with ellipsis

noTruncate

Remove truncation

Size

Size props for controlling component dimensions

Extra small size

Small size

Medium size (default)

Large size

Extra large size

Hide

Hide props for responsive element visibility

mobileHide

Hide element on mobile devices and below (max-mobile: 48rem)

tabletHide

Hide element on tablet devices and below (max-tablet: 64rem)

desktopHide

Hide element on desktop devices and below (max-desktop: 80rem)

Items

Items props for controlling flex item alignment (align-items)

itemsStart

Align items to start (top/left)

itemsEnd

Align items to end (bottom/right)

itemsCenter

Align items to center

itemsBaseline

Align items to baseline

itemsStretch

Stretch items to fill container

Justify

Justify props for controlling flex content alignment (justify-content)

justifyStart

Pack items toward the start of the main axis

justifyEnd

Pack items toward the end of the main axis

justifyCenter

Center items along the main axis

justifyBetween

Distribute items with space between them

justifyAround

Distribute items with space around them

justifyEvenly

Distribute items with equal space around them

justifyStretch

Stretch items to fill the main axis

justifyBaseline

Align items along their baseline on main axis

Position

Position props for controlling CSS position property

relative

Relative positioning

absolute

Absolute positioning

fixed

Fixed positioning

sticky

Sticky positioning

static

Static positioning

Display

Display props for controlling CSS display property

inline

Inline display - flows with text

block

Block display - takes full width, new line

inlineBlock

Inline-block display - inline but with block properties

flex

Flex display - flexbox container

inlineFlex

Inline-flex display - inline flexbox container

grid

Grid display - CSS grid container

inlineGrid

Inline-grid display - inline grid container

contents

Contents display - element's box is removed, children display as if parent didn't exist

table

Table display - behaves like table element

tableCell

Table-cell display - behaves like td element

hidden

Hidden display - element is not visible

Overflow

Overflow props for controlling content overflow behavior

overflowAuto

Auto overflow - show scrollbars if needed

overflowHidden

Hidden overflow - clip content without scrollbars

overflowClip

Clip overflow - hard clip without scrollbars

overflowVisible

Visible overflow - content extends beyond bounds

overflowScroll

Scroll overflow - always show scrollbars

overflowXAuto

Auto overflow on X-axis only

overflowYAuto

Auto overflow on Y-axis only

overflowXHidden

Hidden overflow on X-axis only

overflowYHidden

Hidden overflow on Y-axis only

overflowXClip

Clip overflow on X-axis only

overflowYClip

Clip overflow on Y-axis only

overflowXVisible

Visible overflow on X-axis only

overflowYVisible

Visible overflow on Y-axis only

overflowXScroll

Scroll overflow on X-axis only

overflowYScroll

Scroll overflow on Y-axis only

Wrap

Wrap props for controlling flex wrapping behavior

flexWrap

Allow flex items to wrap to new lines when container is too narrow

flexNoWrap

Force flex items to stay on single line (may overflow)

flexWrapReverse

Wrap flex items in reverse order (last items wrap first)

Gap

Gap props for controlling spacing between children

gap

Enable gap spacing between children

noGap

Disable gap spacing

Flex Direction

Flex direction props for controlling flex layout direction

row

Flex direction row (horizontal)

column

Flex direction column (vertical)

rowReverse

Flex direction row-reverse

columnReverse

Flex direction column-reverse

Reverse

Reverse props for reversing child order

reverse

Reverse the order of children

Appearance

Appearance props for controlling component colors

primary

Primary color appearance (gray)

brand

Brand color appearance (blue)

accent

Accent color appearance (rose)

secondary

Secondary color appearance (gray)

tertiary

Tertiary color appearance

success

Success color appearance (green)

danger

Danger color appearance (red)

warning

Warning color appearance (amber)

info

Info color appearance (cyan)

link

Link color appearance (blue, for hyperlinks)

inherit

Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables

Border

Border props for controlling component borders

border

Enable border on all sides

borderT

Enable border on top

borderB

Enable border on bottom

borderL

Enable border on left

borderR

Enable border on right

borderX

Enable border on left and right

borderY

Enable border on top and bottom

noBorder

Disable all borders

Shadow

Shadow props for controlling drop shadows

shadow

Enable drop shadow

noShadow

Disable drop shadow

Ring

Ring props for controlling focus rings

ring

Enable focus ring

noRing

Disable focus ring

Shape

Shape props for controlling component border radius

pill

Fully rounded corners (circular)

sharp

No rounded corners (square)

rounded

Medium rounded corners (default)

Padding

Padding props for controlling internal spacing

padding

Enable internal padding

paddingX

Enable only horizontal padding

paddingY

Enable only vertical padding

noPadding

Disable internal padding

Shape

Shape props for controlling component border radius

pill

Fully rounded corners (circular)

sharp

No rounded corners (square)

rounded

Medium rounded corners (default)

Variant

Variant props for controlling component style variations

filled

Filled variant - solid background with contrasting text color

outline

Outline variant - transparent background with border and colored text (default)

Transition

Transition props for controlling animation effects

transition

Enable smooth transitions between states

noTransition

Disable transitions for instant state changes

Width

Width props for controlling component width

wFull

Set width to 100%

wFit

Set width to fit-content

wAuto

Set width to auto

wScreen

Set width to 100vw (viewport width), removes max-width constraint

Height

Height props for controlling component height

hFit

Set height to fit-content

hFull

Set height to 100%

hAuto

Set height to auto

hScreen

Set height to 100vh (viewport height), removes max-height constraint

Transparent

Transparent prop for disabling background color

transparent

Disable background color - makes component background transparent

Responsive

Responsive prop for enabling breakpoint-specific sizing

responsive

Enable responsive sizing - uses breakpoint-specific classes for font size, padding, and gap

Placement

Placement props for positioning floating elements relative to their anchor

top

Position above anchor, centered horizontally (default)

topStart

Position above anchor, aligned to start (left)

topEnd

Position above anchor, aligned to end (right)

bottom

Position below anchor, centered horizontally

bottomStart

Position below anchor, aligned to start (left)

bottomEnd

Position below anchor, aligned to end (right)

left

Position to the left of anchor, centered vertically

leftStart

Position to the left of anchor, aligned to top

leftEnd

Position to the left of anchor, aligned to bottom

right

Position to the right of anchor, centered vertically

rightStart

Position to the right of anchor, aligned to top

rightEnd

Position to the right of anchor, aligned to bottom

Pointer Events

Pointer events props for controlling element interactivity

pointerEventsNone

Disable pointer events - clicks pass through the element

pointerEventsAuto

Enable pointer events (default browser behavior)

Min Width

Min-width props for popup/floating components. When enabled, applies a size-dependent minimum width via --popup-min-w CSS variable.

minWidth

Apply size-dependent minimum width (uses --popup-min-w CSS variable)

Controlled themes:

layout

Max Height

Max-height props for components. When enabled, applies a size-dependent maximum height via --max-height CSS variable.

maxHeight

Apply size-dependent maximum height (uses --max-height CSS variable)

Controlled themes:

layout