Floating Panel

A movable and resizable panel component with controls for minimizing, maximizing, and restoring size.

Anatomy

Usage

<script>
  import {
    ArrowDownLeftIcon,
    DotsGridIcon,
    MaximizeIcon,
    MinusIcon,
    XIcon,
  } from '$lib/icons';
  import {FloatingPanel, Portal} from 'ui-ingredients';
</script>

<FloatingPanel.Root>
  <FloatingPanel.Trigger>Toggle Panel</FloatingPanel.Trigger>
  <Portal>
    <FloatingPanel.Positioner>
      <FloatingPanel.Content>
        <FloatingPanel.Header>
          <FloatingPanel.DragTrigger>
            <DotsGridIcon />
          </FloatingPanel.DragTrigger>
          <FloatingPanel.Title>Floating Panel</FloatingPanel.Title>
          <FloatingPanel.Control>
            <FloatingPanel.StageTrigger stage="minimized">
              <MinusIcon />
            </FloatingPanel.StageTrigger>
            <FloatingPanel.StageTrigger stage="maximized">
              <MaximizeIcon />
            </FloatingPanel.StageTrigger>
            <FloatingPanel.StageTrigger stage="default">
              <ArrowDownLeftIcon />
            </FloatingPanel.StageTrigger>
            <FloatingPanel.CloseTrigger>
              <XIcon />
            </FloatingPanel.CloseTrigger>
          </FloatingPanel.Control>
        </FloatingPanel.Header>
        <FloatingPanel.Body>Content</FloatingPanel.Body>
        <FloatingPanel.ResizeTrigger axis="n" />
        <FloatingPanel.ResizeTrigger axis="e" />
        <FloatingPanel.ResizeTrigger axis="s" />
        <FloatingPanel.ResizeTrigger axis="w" />
        <FloatingPanel.ResizeTrigger axis="ne" />
        <FloatingPanel.ResizeTrigger axis="se" />
        <FloatingPanel.ResizeTrigger axis="sw" />
        <FloatingPanel.ResizeTrigger axis="nw" />
      </FloatingPanel.Content>
    </FloatingPanel.Positioner>
  </Portal>
</FloatingPanel.Root>

API Reference

Root

Prop	Default	Description
`allowOverflow`	`true`	`boolean` Whether the panel should be strictly contained within the boundary when dragging
`animateOnMount`	`true`	`boolean` Whether to run the enter animation when the component mounts.
`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
`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` 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.
`keepMounted`	`true`	`boolean` Whether to keep the component mounted after exit.
`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`		`() => void` Callback that fires when the exit animation of the panel completes.
`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
`resizable`	`true`	`boolean` Whether the panel is resizable
`size`		`Size` The size of the panel
`strategy`	`"fixed"`	`"absolute" \| "fixed"` The strategy to use for positioning
`translations`		`IntlTranslations` The translations for the floating panel.

Body

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

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

CloseTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Content

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

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

Control

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

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

DragTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	drag-trigger
`data-scope`	floating-panel

Header

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

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

Positioner

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

ResizeTrigger

Prop	Default	Description
`axis`		`"n" \| "e" \| "s" \| "w" \| "ne" \| "se" \| "sw" \| "nw"` The axis used to resize the panel.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-axis`	The axis to resize
`data-disabled`	Present when disabled
`data-part`	resize-trigger
`data-scope`	floating-panel

StageTrigger

Prop	Default	Description
`stage`		`"default" \| "minimized" \| "maximized"` The stage to apply when triggered.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	stage-trigger
`data-scope`	floating-panel
`data-stage`	The stage of the stagetrigger

Title

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Trigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

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