Popover

Displays rich content in a portal, triggered by a button.

Code

import {
  Button,
  Input,
  Label,
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>
        Open popover
      </PopoverTrigger>
      <PopoverContent className="tw:w-80">
        <div className="tw:grid tw:gap-4">
          <PopoverHeader>
            <PopoverTitle>Application plan</PopoverTitle>
            <PopoverDescription>
              Set the details for this field.
            </PopoverDescription>
          </PopoverHeader>
          <div className="tw:grid tw:gap-2">
            <div className="tw:grid tw:grid-cols-3 tw:items-center tw:gap-4">
              <Label htmlFor="product">Product</Label>
              <Input
                id="product"
                defaultValue="Urea"
                className="tw:col-span-2 tw:h-8"
              />
            </div>
            <div className="tw:grid tw:grid-cols-3 tw:items-center tw:gap-4">
              <Label htmlFor="rate">Rate</Label>
              <Input
                id="rate"
                defaultValue="180"
                className="tw:col-span-2 tw:h-8"
              />
            </div>
            <div className="tw:grid tw:grid-cols-3 tw:items-center tw:gap-4">
              <Label htmlFor="unit">Unit</Label>
              <Input
                id="unit"
                defaultValue="lb/acre"
                className="tw:col-span-2 tw:h-8"
              />
            </div>
            <div className="tw:grid tw:grid-cols-3 tw:items-center tw:gap-4">
              <Label htmlFor="acres">Acres</Label>
              <Input
                id="acres"
                defaultValue="120"
                className="tw:col-span-2 tw:h-8"
              />
            </div>
          </div>
        </div>
      </PopoverContent>
    </Popover>
  );
}

Composition

Use the following composition to build a Popover:

Popover
├── PopoverTrigger
└── PopoverContent

Basic

A simple popover with a header, title, and description.

Code

import {
  Button,
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <>
      <Popover>
        <PopoverTrigger
          render={<Button variant="outline" className="tw:w-fit" />}
        >
          Open Popover
        </PopoverTrigger>
        <PopoverContent align="start">
          <PopoverHeader>
            <PopoverTitle>Application plan</PopoverTitle>
            <PopoverDescription>
              Set the details for this field.
            </PopoverDescription>
          </PopoverHeader>
        </PopoverContent>
      </Popover>
    </>
  );
}

Align

Use the align prop on PopoverContent to control the horizontal alignment.

Code

import {
  Button,
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <>
      <div className="tw:flex tw:gap-6">
        <Popover>
          <PopoverTrigger render={<Button variant="outline" size="sm" />}>
            Start
          </PopoverTrigger>
          <PopoverContent
            align="start"
            aria-label="Start-aligned popover"
            className="tw:w-40"
          >
            Aligned to start
          </PopoverContent>
        </Popover>
        <Popover>
          <PopoverTrigger render={<Button variant="outline" size="sm" />}>
            Center
          </PopoverTrigger>
          <PopoverContent
            align="center"
            aria-label="Center-aligned popover"
            className="tw:w-40"
          >
            Aligned to center
          </PopoverContent>
        </Popover>
        <Popover>
          <PopoverTrigger render={<Button variant="outline" size="sm" />}>
            End
          </PopoverTrigger>
          <PopoverContent
            align="end"
            aria-label="End-aligned popover"
            className="tw:w-40"
          >
            Aligned to end
          </PopoverContent>
        </Popover>
      </div>
    </>
  );
}

With Form

A popover with form fields inside.

Code

import {
  Button,
  Field,
  FieldGroup,
  FieldLabel,
  Input,
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <>
      <Popover>
        <PopoverTrigger render={<Button variant="outline" />}>
          Open Popover
        </PopoverTrigger>
        <PopoverContent className="tw:w-64" align="start">
          <PopoverHeader>
            <PopoverTitle>Application rate</PopoverTitle>
            <PopoverDescription>
              Set the planned rate for this field.
            </PopoverDescription>
          </PopoverHeader>
          <FieldGroup className="tw:gap-4">
            <Field orientation="horizontal">
              <FieldLabel htmlFor="rate" className="tw:w-1/2">
                Rate
              </FieldLabel>
              <Input id="rate" defaultValue="180" />
            </Field>
            <Field orientation="horizontal">
              <FieldLabel htmlFor="unit" className="tw:w-1/2">
                Unit
              </FieldLabel>
              <Input id="unit" defaultValue="lb/acre" />
            </Field>
          </FieldGroup>
        </PopoverContent>
      </Popover>
    </>
  );
}

API

Popover

Groups a popover’s parts without rendering an HTML element.

Props

children

children?: React.ReactNode

The popover’s parts.

defaultOpen

defaultOpen?: boolean

Whether the popover is initially open. Defaults to false.

defaultTriggerId

defaultTriggerId?: string | null

ID of the trigger associated with an initially open popover.

modal

modal?: boolean | "trap-focus"

Whether opening the popover limits interaction outside it. Defaults to false.

onOpenChange

onOpenChange?: ((open: boolean, eventDetails: PopoverPrimitive.Root.ChangeEventDetails) => void)

Event handler called when the popover is opened or closed.

onOpenChangeComplete

onOpenChangeComplete?: ((open: boolean) => void)

Event handler called after popover animations complete.

open

open?: boolean

Whether the popover is currently open.

triggerId

triggerId?: string | null

ID of the trigger associated with a controlled popover.

PopoverContent

Includes a portal and positioned popover. Renders a <div> element by default and accepts standard <div> props. Use it with PopoverTitle and PopoverDescription to give it an accessible name and description.

Props

align

align?: Align = "center"

The alignment of the popover relative to its trigger. Defaults to "center".

alignOffset

alignOffset?: number | OffsetFunction = 0

The offset from the aligned position, in pixels. Defaults to 0.

className

className?: string

CSS class applied to the popover.

finalFocus

finalFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => void | boolean | HTMLElement | null)

Determines the element to focus when the popover is closed.

initialFocus

initialFocus?: boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => void | boolean | HTMLElement | null)

Determines the element to focus when the popover is opened.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>

Allows replacing the popover element or composing it with another component.

side

side?: Side = "bottom"

The side of the trigger where the popover is placed. Defaults to "bottom".

sideOffset

sideOffset?: number | OffsetFunction = 4

The offset from the trigger, in pixels. Defaults to 4.

style

style?: React.CSSProperties | ((state: PopoverPopupState) => React.CSSProperties | undefined)

Style applied to the popover, or a function based on its state.

PopoverDescription

Provides the popover’s accessible description. Renders a <p> element by default and accepts standard <p> props.

Props

className

className?: string

CSS class applied to the popover description.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverDescriptionState>

Allows replacing the description element or composing it with another component.

style

style?: React.CSSProperties | ((state: PopoverDescriptionState) => React.CSSProperties | undefined)

Style applied to the popover description, or a function based on its state.

PopoverHeader

Groups PopoverTitle and PopoverDescription. Renders a <div> element and accepts standard <div> props.

PopoverTitle

Provides the popover’s accessible name. Renders an <h2> element by default and accepts standard heading props.

Props

className

className?: string

CSS class applied to the popover title.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>

Allows replacing the title element or composing it with another component.

style

style?: React.CSSProperties | ((state: PopoverTitleState) => React.CSSProperties | undefined)

Style applied to the popover title, or a function based on its state.

PopoverTrigger

Opens the associated popover. Renders a <button> element by default and accepts standard <button> props.

Props

className

className?: string | ((state: PopoverTriggerState) => string | undefined)

CSS class applied to the trigger, or a function based on its state.

closeDelay

closeDelay?: number

How long to wait before closing a hover-opened popover, in milliseconds. Defaults to 0.

delay

delay?: number

How long to wait before opening the popover on hover, in milliseconds. Defaults to 300.

id

id?: string

ID used to identify the active trigger in controlled mode.

nativeButton

nativeButton?: boolean

Whether render produces a native <button> element. Defaults to true.

openOnHover

openOnHover?: boolean

Whether hovering the trigger also opens the popover. Defaults to false.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>

Allows replacing the trigger element or composing it with another component.

style

style?: React.CSSProperties | ((state: PopoverTriggerState) => React.CSSProperties | undefined)

Style applied to the trigger, or a function based on its state.