Floating Panel

A panel that floats over the page, which the user can drag, resize, and minimize.

Usage

Code
import { FloatingPanel } from '@leverui/components';
Code
<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.

Code
<FloatingPanel.ResizeTriggers />
Code
<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.

Code
<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.

This way you can access the panel state and methods from outside the panel.

Use RootProvider + useFloatingPanel or Root, 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 position
  • minimized — collapse the panel to a compact height (header only)
  • maximized — expand the panel to fill the available boundary
Code
<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.

Drag the resize handles. The size stays between the min and the max.

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

PropDefaultTypeDescription
allowOverflowtruebooleanLet the panel be dragged past its boundary.
dir'ltr''ltr' | 'rtl'Text direction.
draggabletruebooleanAllow dragging.
gridSize1numberGrid the panel snaps to.
lazyMounttruebooleanRender on first open.
resizabletruebooleanAllow resizing.
restoreFocustruebooleanReturn focus to the trigger on close.
strategy'fixed''absolute' | 'fixed'CSS positioning method.
unmountOnExittruebooleanRemove from the page on close.
asdivNative tag nameHTML tag to render.
asChild—Solid render functionRender your own element with the root's props.
unstyled—booleanTurn off the Lever UI styles.
closeOnEscape—booleanClose on Escape.
defaultOpenfalsebooleanOpen on first render.
defaultPosition—PointPosition on first render.
defaultSize—SizeStarting size.
disabled—booleanDisable the panel.
finalFocusEl—() => HTMLElement | nullElement focused on close. Default: the trigger.
getAnchorPosition—(details: AnchorPositionDetails) => PointReturns where the panel opens.
getBoundaryEl—() => HTMLElement | nullReturns the panel's boundary element.
id—stringUnique ID.
ids—Element ID mapYour own IDs for the panel's elements.
immediate—booleanApply present changes now, not next frame.
initialFocusEl—() => HTMLElement | nullElement focused on open.
lockAspectRatio—booleanKeep the aspect ratio while resizing.
maxSize—SizeLargest size.
minSize—SizeSmallest size.
onExitComplete—VoidFunctionCalled when the closing animation ends.
onOpenChange—(details: OpenChangeDetails) => voidCalled when the panel opens or closes.
onPositionChange—(details: PositionChangeDetails) => voidCalled when dragging moves the panel.
onPositionChangeEnd—(details: PositionChangeDetails) => voidCalled when dragging stops.
onSizeChange—(details: SizeChangeDetails) => voidCalled when resizing changes the size.
onSizeChangeEnd—(details: SizeChangeDetails) => voidCalled when resizing stops.
onStageChange—(details: StageChangeDetails) => voidCalled when the stage changes, such as to minimized.
open—booleanControlled open state.
persistRect—booleanKeep size and position after close.
position—PointControlled position.
present—booleanControlled rendered state.
size—SizePanel size.
skipAnimationOnMountfalsebooleanSkip the opening animation on first mount.
translations—IntlTranslationsTranslated 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.

Code
<FloatingPanel.Content class="notes-panel" style={{ 'max-height': '80vh' }}>
  ...
</FloatingPanel.Content>
Code
@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.