Skip to content
Browse documentation
whisk/ui

Flyout

Position application-owned contextual content at an anchor.

Overview

Flyout positions a controlled, application-owned surface beside an external anchor. It handles placement and asks to dismiss on outside interaction or Escape, but it does not create a trigger, choose ARIA semantics, move focus, or manage the content's interaction model.

Use when

Application code already owns an anchor, controlled state, focus policy, and a named contextual surface.

Use instead

Use DropdownMenu for a compact action list, Modal for a blocking task, Select or Combobox for choosing a value, and Tooltip for brief noninteractive help.

Usage

import { useRef, useState } from "react";
import { Button, Flyout, Heading, Stack, Text } from "@smoothie-framework/whisk-react";

export function ProjectDetailsFlyout() {
  const triggerRef = useRef<HTMLButtonElement | null>(null);
  const [open, setOpen] = useState(false);

  const changeOpen = (nextOpen: boolean) => {
    setOpen(nextOpen);
    if (!nextOpen) queueMicrotask(() => triggerRef.current?.focus());
  };

  return (
    <>
      <Button
        ref={triggerRef}
        aria-expanded={open}
        aria-controls="project-details"
        onClick={() => changeOpen(!open)}
      >
        Project details
      </Button>
      <Flyout
        id="project-details"
        role="region"
        aria-labelledby="project-details-title"
        open={open}
        onOpenChange={changeOpen}
        anchorRef={triggerRef}
      >
        <Stack gap={3} padding={4}>
          <Heading id="project-details-title" level={2}>Atlas</Heading>
          <Text color="subtle">Last deployed 10 minutes ago.</Text>
          <Button variant="secondary" onClick={() => changeOpen(false)}>
            Close details
          </Button>
        </Box>
      </Flyout>
    </>
  );
}

Examples

Anchor a named surface

Flyout has no trigger part. Keep open state, trigger ARIA, and focus return in the host. The anchor must remain connected outside the Flyout while it is open.

import { useRef, useState } from "react";
import { Button, Flyout, Heading, Stack, Text } from "@smoothie-framework/whisk-react";

export function ProjectDetailsFlyout() {
  const triggerRef = useRef<HTMLButtonElement | null>(null);
  const [open, setOpen] = useState(false);

  const changeOpen = (nextOpen: boolean) => {
    setOpen(nextOpen);
    if (!nextOpen) queueMicrotask(() => triggerRef.current?.focus());
  };

  return (
    <>
      <Button
        ref={triggerRef}
        aria-expanded={open}
        aria-controls="project-details"
        onClick={() => changeOpen(!open)}
      >
        Project details
      </Button>
      <Flyout
        id="project-details"
        role="region"
        aria-labelledby="project-details-title"
        open={open}
        onOpenChange={changeOpen}
        anchorRef={triggerRef}
      >
        <Stack gap={3} padding={4}>
          <Heading id="project-details-title" level={2}>Atlas</Heading>
          <Text color="subtle">Last deployed 10 minutes ago.</Text>
          <Button variant="secondary" onClick={() => changeOpen(false)}>
            Close details
          </Button>
        </Stack>
      </Flyout>
    </>
  );
}

Use the helper buttons deliberately

FlyoutItem and FlyoutFooterAction are ordinary buttons. selected sets aria-pressed, but does not create a menu, option list, selection state, or automatic dismissal. Keep those decisions in application code.

import { useRef, useState } from "react";
import {
  Button,
  Flyout,
  FlyoutFooterAction,
  FlyoutFooterActions,
  FlyoutGroupLabel,
  FlyoutItem,
  Stack,
} from "@smoothie-framework/whisk-react";

export function ProjectOptionsFlyout() {
  const triggerRef = useRef<HTMLButtonElement | null>(null);
  const [open, setOpen] = useState(false);

  const changeOpen = (nextOpen: boolean) => {
    setOpen(nextOpen);
    if (!nextOpen) queueMicrotask(() => triggerRef.current?.focus());
  };

  return (
    <>
      <Button
        ref={triggerRef}
        aria-expanded={open}
        aria-controls="project-options"
        onClick={() => changeOpen(!open)}
      >
        Project options
      </Button>
      <Flyout
        id="project-options"
        role="region"
        aria-labelledby="project-options-title"
        open={open}
        onOpenChange={changeOpen}
        anchorRef={triggerRef}
      >
        <Stack gap={3} padding={4}>
          <Box role="group" padding={0} margin={0} borderWidth={0} minWidth={0} aria-labelledby="project-options-title">
            <FlyoutGroupLabel id="project-options-title" variant="section">
              Project options
            </FlyoutGroupLabel>
            <FlyoutItem selected>Show archived</FlyoutItem>
            <FlyoutItem suffix="CSV">Export report</FlyoutItem>
          </Box>
          <FlyoutFooterActions position="sticky">
            <FlyoutFooterAction onClick={() => changeOpen(false)}>
              Close options
            </FlyoutFooterAction>
          </FlyoutFooterActions>
        </Stack>
      </Flyout>
    </>
  );
}

Match a control width

Use matchAnchorWidth for a fixed-position surface that should read as an extension of its trigger. It still clamps to the viewport. This is useful for a custom filter surface, not a substitute for Select or Combobox.

import { useRef, useState } from "react";
import { Button, Flyout, Heading, Stack, Text } from "@smoothie-framework/whisk-react";

export function FilterFlyout() {
  const triggerRef = useRef<HTMLButtonElement | null>(null);
  const [open, setOpen] = useState(false);

  const changeOpen = (nextOpen: boolean) => {
    setOpen(nextOpen);
    if (!nextOpen) queueMicrotask(() => triggerRef.current?.focus());
  };

  return (
    <>
      <Button
        ref={triggerRef}
        aria-expanded={open}
        aria-controls="filter-options"
        onClick={() => changeOpen(!open)}
      >
        Filter projects
      </Button>
      <Flyout
        id="filter-options"
        role="region"
        aria-labelledby="filter-options-title"
        open={open}
        onOpenChange={changeOpen}
        anchorRef={triggerRef}
        matchAnchorWidth
      >
        <Stack gap={3} padding={4}>
          <Heading id="filter-options-title" level={2}>Project status</Heading>
          <Text color="subtle">Choose a status filter in the application.</Text>
        </Stack>
      </Flyout>
    </>
  );
}

Choose the semantic controller

Flyout only provides an anchored surface. It cannot safely stand in for a component whose interaction model is already known.

tsx
// Use DropdownMenu for a compact action list with menu roles and arrow-key navigation.
// Use Modal for a blocking task, focus policy, and dialog semantics.
// Use Select or Combobox when the user chooses a value.
// Use Flyout when the host owns a different, explicit interaction model.

Use absolute positioning only for host-owned geometry

With strategy="absolute", Flyout stays in the anchor's offset parent. Whisk/UI does not calculate its placement or width in this mode, so use it only when the surrounding component CSS already owns that geometry.

tsx
<Flyout
  open={open}
  onOpenChange={setOpen}
  anchorRef={triggerRef}
  strategy="absolute"
>
  <Text>Application-positioned content</Text>
</Flyout>

Props

Component props

PropTypeDefaultDescription
openbooleannoneRequired. The application controls whether the surface is presented. There is no defaultOpen or uncontrolled mode.
onOpenChange(open: boolean) => voidnoneRequired. Receive dismissal requests from outside interaction, focus leaving, Escape, and a closing native owner.
anchorRef{ current: HTMLElement | null }noneRequired. Point to a connected element outside the Flyout in the same document and keep that anchor mounted while open.
placementtop | bottom | left | rightbottomChoose the primary side of the anchor.
alignstart | center | endstartAlign the surface along the anchor's cross axis.
offset | crossAxisOffsetnumber4 | 0Set a nonnegative distance from the anchor, then optionally shift across its cross axis.
sizesm | md | lgmdSet the visual density of the surface.
matchAnchorWidthbooleanfalseMatch the anchor width while using fixed positioning, still bounded by the viewport.
minimumWidth | minimumAnchorWidthOffsetnumbernoneKeep a fixed-position surface at least this wide, or at least the anchor width plus the offset. Both respect the viewport.
strategyfixed | absolutefixedfixed uses a native manual popover in the top layer and positions it automatically. With absolute, the surface stays in its offset parent and application CSS owns geometry.
role | aria-label | aria-labelledbynative div attributesnoneFlyout supplies no semantic role or accessible name. Choose them for the interaction that your host implements.
FlyoutItembutton props & { selected?, startElement?, suffix?, size? }noneRender an ordinary button, optionally with aria-pressed state. It is not a menu item, option, or automatic selection controller.
FlyoutGroupLabeldiv props & { variant? }noneRender visible group text. Connect it to a host-owned role=group with its id when the group needs a programmatic name.
FlyoutFooterActions | FlyoutFooterActiondiv props & FlyoutItem propsnoneLay out trailing actions. position is scroll or sticky; a footer action is an ordinary button.

Accessibility

Flyout is presentational. The host must create a keyboard-reachable trigger, keep aria-expanded and aria-controls synchronized, select a role and accessible name, and decide where focus goes on open and close. Flyout requests dismissal when focus or a pointer moves outside, and on Escape, but it does not return focus or trap it. Do not apply menu roles or arrow-key navigation unless the surface is actually a menu. Use DropdownMenu for that pattern, Modal for a blocking task, and Tooltip for short noninteractive help.

Content guidance

Give the surface a short, clear name and keep its copy scoped to the anchored task. Group labels name the choices below them. Start FlyoutItem and FlyoutFooterAction labels with a specific verb.