Floating Panel

Used to display content in a non-modal floating window.

Anatomy

<FloatingPanel.Root>
  <FloatingPanel.Trigger />
  <FloatingPanel.Positioner>
    <FloatingPanel.Content>
      <FloatingPanel.DragTrigger>
        <FloatingPanel.Header>
          <FloatingPanel.Title />
          <FloatingPanel.Control>
            <FloatingPanel.StageTrigger />
            <FloatingPanel.CloseTrigger />
          </FloatingPanel.Control>
        </FloatingPanel.Header>
      </FloatingPanel.DragTrigger>
      <FloatingPanel.Body />
      <FloatingPanel.ResizeTrigger />
    </FloatingPanel.Content>
  </FloatingPanel.Positioner>
</FloatingPanel.Root>

Examples

Controlled size

To control the size of the floating panel programmatically, you can pass the size onResize prop to the machine.

Controlled position

To control the position of the floating panel programmatically, you can pass the position and onPositionChange prop to the machine.

Anchor Position

Use the getAnchorPosition function to compute the initial position of the floating panel. This function is called when the panel is opened and receives the triggerRect and boundaryRect.

Open State

To control the open state of the floating panel programmatically, you can pass the open and onOpenChange prop to the machine.

Lazy Mount

To lazy mount the floating panel, you can pass the lazyMount prop to the machine.

Context

To access the context of the floating panel, you can use the useFloatingPanelContext hook or the FloatingPanel.Context component.

API Reference

Props

Root

Prop	Default	Type
`allowOverflow`	`true`	`boolean` Whether the panel should be strictly contained within the boundary when dragging
`closeOnEscape`		`boolean` Whether the panel should close when the escape key is pressed
`defaultOpen`	`false`	`boolean` The initial open state of the panel when rendered. Use when you don't need to control the open state of the panel.
`defaultPosition`		`Point` The initial position of the panel when rendered. Use when you don't need to control the position of the panel.
`defaultSize`		`Size` The default size of the panel
`dir`	`'ltr'`	`'ltr' \| 'rtl'` The document's text/writing direction.
`disabled`		`boolean` Whether the panel is disabled
`draggable`	`true`	`boolean` Whether the panel is draggable
`getAnchorPosition`		`(details: AnchorPositionDetails) => Point` Function that returns the initial position of the panel when it is opened. If provided, will be used instead of the default position.
`getBoundaryEl`		`() => HTMLElement \| null` The boundary of the panel. Useful for recalculating the boundary rect when the it is resized.
`gridSize`	`1`	`number` The snap grid for the panel
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ trigger: string; positioner: string; content: string; title: string; header: string }>` The ids of the elements in the floating panel. Useful for composition.
`immediate`		`boolean` Whether to synchronize the present change immediately or defer it to the next frame
`lazyMount`	`false`	`boolean` Whether to enable lazy mounting
`lockAspectRatio`		`boolean` Whether the panel is locked to its aspect ratio
`maxSize`		`Size` The maximum size of the panel
`minSize`		`Size` The minimum size of the panel
`onExitComplete`		`VoidFunction` Function called when the animation ends in the closed state
`onOpenChange`		`(details: OpenChangeDetails) => void` Function called when the panel is opened or closed
`onPositionChange`		`(details: PositionChangeDetails) => void` Function called when the position of the panel changes via dragging
`onPositionChangeEnd`		`(details: PositionChangeDetails) => void` Function called when the position of the panel changes via dragging ends
`onSizeChange`		`(details: SizeChangeDetails) => void` Function called when the size of the panel changes via resizing
`onSizeChangeEnd`		`(details: SizeChangeDetails) => void` Function called when the size of the panel changes via resizing ends
`onStageChange`		`(details: StageChangeDetails) => void` Function called when the stage of the panel changes
`open`		`boolean` The controlled open state of the panel
`persistRect`		`boolean` Whether the panel size and position should be preserved when it is closed
`position`		`Point` The controlled position of the panel
`present`		`boolean` Whether the node is present (controlled by the user)
`resizable`	`true`	`boolean` Whether the panel is resizable
`size`		`Size` The size of the panel
`skipAnimationOnMount`	`false`	`boolean` Whether to allow the initial presence animation.
`strategy`	`'fixed'`	`'absolute' \| 'fixed'` The strategy to use for positioning
`translations`		`IntlTranslations` The translations for the floating panel.
`unmountOnExit`	`false`	`boolean` Whether to unmount on exit.

Body

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	floating-panel
`[data-part]`	body
`[data-dragging]`	Present when in the dragging state
`[data-minimized]`	Present when minimized
`[data-maximized]`	Present when maximized
`[data-staged]`	Present when not in default stage

CloseTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Content

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	floating-panel
`[data-part]`	content
`[data-state]`	"open" \| "closed"
`[data-dragging]`	Present when in the dragging state
`[data-topmost]`	Present when topmost
`[data-behind]`	Present when not topmost
`[data-minimized]`	Present when minimized
`[data-maximized]`	Present when maximized
`[data-staged]`	Present when not in default stage

Control

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	floating-panel
`[data-part]`	control
`[data-disabled]`	Present when disabled
`[data-stage]`	The stage of the control
`[data-minimized]`	Present when minimized
`[data-maximized]`	Present when maximized
`[data-staged]`	Present when not in default stage

DragTrigger

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	floating-panel
`[data-part]`	drag-trigger
`[data-disabled]`	Present when disabled

Header

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	floating-panel
`[data-part]`	header
`[data-dragging]`	Present when in the dragging state
`[data-topmost]`	Present when topmost
`[data-behind]`	Present when not topmost
`[data-minimized]`	Present when minimized
`[data-maximized]`	Present when maximized
`[data-staged]`	Present when not in default stage

Positioner

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

CSS Variable	Description
`--width`	The width of the element
`--height`	The height of the element
`--x`	The x position for transform
`--y`	The y position for transform
`--reference-width`	The width of the reference element
`--reference-height`	The height of the root
`--available-width`	The available width in viewport
`--available-height`	The available height in viewport
`--z-index`	The z-index value
`--transform-origin`	The transform origin for animations

ResizeTrigger

Renders a <div> element.

Prop	Default	Type
`axis`		`ResizeTriggerAxis` The axis of the resize handle
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	floating-panel
`[data-part]`	resize-trigger
`[data-disabled]`	Present when disabled
`[data-axis]`	The axis to resize

RootProvider

Prop	Default	Type
`value`		`UseFloatingPanelReturn`
`immediate`		`boolean` Whether to synchronize the present change immediately or defer it to the next frame
`lazyMount`	`false`	`boolean` Whether to enable lazy mounting
`onExitComplete`		`VoidFunction` Function called when the animation ends in the closed state
`skipAnimationOnMount`	`false`	`boolean` Whether to allow the initial presence animation.
`unmountOnExit`	`false`	`boolean` Whether to unmount on exit.

StageTrigger

Renders a <button> element.

Prop	Default	Type
`stage`		`Stage` The stage of the panel
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Title

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Trigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	floating-panel
`[data-part]`	trigger
`[data-state]`	"open" \| "closed"
`[data-dragging]`	Present when in the dragging state

Context

API

Property	Type
`open`	`boolean` Whether the panel is open
`setOpen`	`(open: boolean) => void` Function to open or close the panel
`dragging`	`boolean` Whether the panel is being dragged
`resizing`	`boolean` Whether the panel is being resized
`position`	`Point` The position of the panel
`setPosition`	`(position: Point) => void` Function to set the position of the panel
`size`	`Size` The size of the panel
`setSize`	`(size: Size) => void` Function to set the size of the panel
`minimize`	`VoidFunction` Function to minimize the panel
`maximize`	`VoidFunction` Function to maximize the panel
`restore`	`VoidFunction` Function to restore the panel before it was minimized or maximized
`resizable`	`boolean` Whether the panel is resizable
`draggable`	`boolean` Whether the panel is draggable