Floating Panel
A panel that floats over the page, which the user can drag, resize, and minimize.
Usage
import { FloatingPanel } from '@leverui/components';
<FloatingPanel.Root>
<FloatingPanel.Trigger />
<FloatingPanel.Positioner>
<FloatingPanel.Content>
<FloatingPanel.Header>
<FloatingPanel.DragTrigger>
<FloatingPanel.Title />
</FloatingPanel.DragTrigger>
<FloatingPanel.Control>
<FloatingPanel.StageTrigger />
<FloatingPanel.CloseTrigger />
</FloatingPanel.Control>
</FloatingPanel.Header>
<FloatingPanel.Body />
<FloatingPanel.ResizeTriggers />
</FloatingPanel.Content>
</FloatingPanel.Positioner>
</FloatingPanel.Root>
Shortcuts
FloatingPanelResizeTriggers
FloatingPanel.ResizeTriggers renders one FloatingPanel.ResizeTrigger for
each edge and corner.
<FloatingPanel.ResizeTriggers />
<FloatingPanel.ResizeTrigger placement="n" />
<FloatingPanel.ResizeTrigger placement="s" />
<FloatingPanel.ResizeTrigger placement="e" />
<FloatingPanel.ResizeTrigger placement="w" />
<FloatingPanel.ResizeTrigger placement="ne" />
<FloatingPanel.ResizeTrigger placement="nw" />
<FloatingPanel.ResizeTrigger placement="se" />
<FloatingPanel.ResizeTrigger placement="sw" />
Pass axes to render only some handles.
<FloatingPanel.ResizeTriggers axes={['s', 'e', 'se']} />
Examples
Controlled Open
Use the open and onOpenChange props to control the visibility of the panel.
Store
An alternative way to control the floating panel is to use the RootProvider component and the useFloatingPanel store hook.
Store
useFloatingPanel with FloatingPanel.RootProvider to access panel state and methods from outside the panel tree.This way you can access the panel state and methods from outside the panel.
Use
RootProvider + useFloatingPanelorRoot, not both.
Stages
Use the stage prop on FloatingPanel.StageTrigger to add buttons and minimize, maximum and restore the panel stage.
Here are the available stages:
default— restore the panel to its normal size and positionminimized— collapse the panel to a compact height (header only)maximized— expand the panel to fill the available boundary
<FloatingPanel.StageTrigger stage="minimized" />
Multiple
Render multiple FloatingPanel.Root instances to show several panels at once. Each root manages its own open state, position, and size independently.
Overlay
Use the createOverlay function to open a floating panel programmatically from anywhere in your app. Render the overlay's Viewport component and call .open() to show the panel.
Context
Use useFloatingPanelContext inside the panel to call minimize, maximize, restore, setPosition, and setSize programmatically.
Disable Drag
Set draggable={false} to prevent the panel from being moved by the user.
Disable Resize
Set resizable={false} to prevent the panel from being resized by the user.
Resize Axes
Pass the axes prop to FloatingPanel.ResizeTriggers to limit which resize handles are rendered.
Min/Max
Use the minSize and maxSize props to constrain how small or large the panel can be resized.
Anchor Position
Use the getAnchorPosition prop to position the panel relative to the trigger element when it opens.
Boundary
Use getBoundaryEl with allowOverflow={false} to confine the panel within a specific container.
Drag boundary
Position
Use the position and onPositionChange props to control the panel's position programmatically.
x: 16, y: 100
Size
Use the size and onSizeChange props to control the panel's dimensions programmatically.
Prevent Overflow
Set allowOverflow={false} to prevent the panel from being dragged beyond the viewport edges.
RTL
Set the dir="rtl" prop to support right-to-left layouts.
Guides
The title names the panel. Give every control a clear label. defaultSize sets
the starting size and minSize the smallest. For a task that must block the
page, use a Dialog. Render the Positioner inside a Portal.
Open a panel from code anywhere with createOverlay.
Props
Root
| Prop | Default | Type | Description |
|---|---|---|---|
allowOverflow | true | boolean | Let the panel be dragged past its boundary. |
dir | 'ltr' | 'ltr' | 'rtl' | Text direction. |
draggable | true | boolean | Allow dragging. |
gridSize | 1 | number | Grid the panel snaps to. |
lazyMount | true | boolean | Render on first open. |
resizable | true | boolean | Allow resizing. |
restoreFocus | true | boolean | Return focus to the trigger on close. |
strategy | 'fixed' | 'absolute' | 'fixed' | CSS positioning method. |
unmountOnExit | true | boolean | Remove from the page on close. |
as | div | Native tag name | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the root's props. |
unstyled | — | boolean | Turn off the Lever UI styles. |
closeOnEscape | — | boolean | Close on Escape. |
defaultOpen | false | boolean | Open on first render. |
defaultPosition | — | Point | Position on first render. |
defaultSize | — | Size | Starting size. |
disabled | — | boolean | Disable the panel. |
finalFocusEl | — | () => HTMLElement | null | Element focused on close. Default: the trigger. |
getAnchorPosition | — | (details: AnchorPositionDetails) => Point | Returns where the panel opens. |
getBoundaryEl | — | () => HTMLElement | null | Returns the panel's boundary element. |
id | — | string | Unique ID. |
ids | — | Element ID map | Your own IDs for the panel's elements. |
immediate | — | boolean | Apply present changes now, not next frame. |
initialFocusEl | — | () => HTMLElement | null | Element focused on open. |
lockAspectRatio | — | boolean | Keep the aspect ratio while resizing. |
maxSize | — | Size | Largest size. |
minSize | — | Size | Smallest size. |
onExitComplete | — | VoidFunction | Called when the closing animation ends. |
onOpenChange | — | (details: OpenChangeDetails) => void | Called when the panel opens or closes. |
onPositionChange | — | (details: PositionChangeDetails) => void | Called when dragging moves the panel. |
onPositionChangeEnd | — | (details: PositionChangeDetails) => void | Called when dragging stops. |
onSizeChange | — | (details: SizeChangeDetails) => void | Called when resizing changes the size. |
onSizeChangeEnd | — | (details: SizeChangeDetails) => void | Called when resizing stops. |
onStageChange | — | (details: StageChangeDetails) => void | Called when the stage changes, such as to minimized. |
open | — | boolean | Controlled open state. |
persistRect | — | boolean | Keep size and position after close. |
position | — | Point | Controlled position. |
present | — | boolean | Controlled rendered state. |
size | — | Size | Panel size. |
skipAnimationOnMount | false | boolean | Skip the opening animation on first mount. |
translations | — | IntlTranslations | Translated text. |
Customize with CSS
Load the package stylesheet first. Each part has a
leverui-floating-panel__<part> class and a part attribute, such as
data-floating-panel-content. A selector that starts from an element around
Root does not reach a part in a portal. Use a class on the part for one
panel, a selector for every panel, or style for a single value.
<FloatingPanel.Content class="notes-panel" style={{ 'max-height': '80vh' }}>
...
</FloatingPanel.Content>
@layer leverui.recipes {
.notes-panel[data-leverui-floating-panel-css] {
border: 1px solid var(--leverui-colors-border);
}
}
--leverui-colors-bg-panel sets the content's default background. unstyled
on a part or on Root turns off its Lever UI styles.