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
Atlas
Last deployed 10 minutes ago.
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.
Atlas
Last deployed 10 minutes ago.
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.
Project status
Choose a status filter in the application.
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.
// 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.
<Flyout
open={open}
onOpenChange={setOpen}
anchorRef={triggerRef}
strategy="absolute"
>
<Text>Application-positioned content</Text>
</Flyout>Props
Component props
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.