For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/popover.md.

Popover

Show details or actions next to an element.

Basic usage

Click the trigger to open. Escape, an outside click or focus leaving dismisses the panel.

basic.tsx
import { Button, Popover } from '@ifhover/leaf-ui';

export function PopoverBasic() {
  return (
    <Popover title="Project details" content="See project details and recent updates here.">
      <Button variant="outline">View details</Button>
    </Popover>
  );
}

Examples

Hover details

Hover mode is for descriptive content and also supports keyboard focus. Use the default click mode for forms or buttons.

hover.tsx
import { Button, Popover } from '@ifhover/leaf-ui';

export function PopoverHover() {
  return (
    <Popover
      title="Project details"
      content="See project details and recent updates here."
      trigger="hover"
    >
      <Button variant="outline">Hover for details</Button>
    </Popover>
  );
}

Controlled editing

Control visibility with open and onOpenChange. Saving updates the project name; reopening after an unsaved close restores the saved value. Click mode moves focus into the panel by default; saving or pressing Escape returns it to the trigger.

Project name: Leaf Garden
controlled.tsx
import { Button, Flex, Form, FormField, Input, Popover, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function PopoverControlled() {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState('Leaf Garden');
  const [draft, setDraft] = useState(name);
  return (
    <Flex direction="column" gap="md" align="start">
      <Popover
        title="Edit project"
        width={280}
        open={open}
        onOpenChange={(next) => {
          if (next) setDraft(name);
          setOpen(next);
        }}
        content={
          <Form
            layout="vertical"
            onSubmit={(event) => {
              event.preventDefault();
              setName(draft.trim());
              setOpen(false);
            }}
          >
            <FormField label="Project name">
              <Input
                name="projectName"
                value={draft}
                onChange={(event) => setDraft(event.currentTarget.value)}
                required
              />
            </FormField>
            <Button type="submit" disabled={!draft.trim()}>
              Save and close
            </Button>
          </Form>
        }
      >
        <Button variant="outline">Edit project</Button>
      </Popover>
      <Text role="status" tone="muted">
        Project name: {name}
      </Text>
    </Flex>
  );
}

Panel placement

Set the preferred position with placement; it adjusts when space is limited.

Top
Bottom
Left
Right
placements.tsx
import { Button, Flex, Grid, Popover, Text } from '@ifhover/leaf-ui';

const placements = [
  { placement: 'top', label: 'Top' },
  { placement: 'bottom', label: 'Bottom' },
  { placement: 'left', label: 'Left' },
  { placement: 'right', label: 'Right' },
] as const;

export function PopoverPlacements() {
  return (
    <Flex direction="column" gap="md">
      {placements.map(({ placement, label }) => (
        <Grid
          key={placement}
          role="group"
          aria-label={label}
          columns={{ xs: 1, sm: 2 }}
          gap="8px"
          align="center"
        >
          <Text tone="muted">{label}</Text>
          <Popover
            placement={placement}
            title="Project details"
            content="See project details and recent updates here."
          >
            <Button variant="outline">View details</Button>
          </Popover>
        </Grid>
      ))}
    </Flex>
  );
}

API

Popover API

Configure popup content, triggers and controlled visibility.

The trigger must forward its ref and events. Provide aria-label when there is no title. Tab can leave the panel; focus is not trapped. See PopupOptions for shared popup options.

PropertyTypeDefaultDescription
titleReactNode—Popover title.
contentReactNodeRequiredPopover content; use click mode for interactive content.
childrenReactElement< HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement>; disabled?: boolean } >RequiredTrigger element, with ref and event support
trigger'click' | 'hover''click'Trigger mode
placement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end''top'Popup placement
disabledbooleanfalseDisable interaction.
openboolean—Controlled open state.
defaultOpenbooleanfalseInitial open state for uncontrolled usage.
onOpenChange(open: boolean) => void—Open state change
autoFocusbooleantrueIn click mode, focus the first focusable element or the panel if none exists; hover mode does not move focus.
aria-labelstring—Accessible name for a popover without a visible title.
widthnumber | string'max-content'Popover width; numbers are pixels.
maxWidthnumber | string320Maximum popover width; numbers are pixels.
enterDelaynumber100Delay in milliseconds before opening on hover.
leaveDelaynumber100Delay in milliseconds before closing after pointer leave.
classNamestring—CSS class applied to the popover panel.
styleCSSProperties—Inline styles applied to the popover panel.
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—Placement relative to the trigger.
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—Custom popup styles.
popupRender(content: React.ReactNode) => React.ReactNode—Wrap or extend popup content; retain the supplied content to preserve interaction.
getPopupContainer() => Element | DocumentFragment—Return a popup container, including a ShadowRoot.