Documentation

svelte-windows API guide

Build desktop-like interfaces in Svelte with drag, resize, stacking, mobile touch handling, and iframe-safe focus behavior.

Open Playground View Source

Quick start

Install the package, then place one or more windows inside a manager.

npm install svelte-windows

Core model

WindowManager sets up global move/up handlers and provides context.
Window registers itself, manages z-order, and renders drag/resize handles.
MouseContext multiplexes movement to one active drag/resize target.
WindowContext tracks active window and stacking history.

Basic usage

Use snippet children to receive the manager context. Define draggable hit areas with windowDragRegions.

Example.svelte

WindowManager props

You can pass your own context instances when coordinating multiple managers or integrating external window state.

Prop	Type	Default	Required	Description
children	Snippet<[context]>	undefined	No	Snippet render function that receives `{ mouseContext, windowContext, desktop }`.
mouseContext	MouseContext	new MouseContext()	No	Optional shared mouse coordinator instance for advanced composition.
windowContext	WindowContext	new WindowContext()	No	Optional shared window stack manager instance.

WindowDragConfig

Each drag region requires width and height and can be positioned using either top or bottom plus either left or right. You can optionally pass color to visualize a drag region while designing custom chrome.

Vertical anchor: choose exactly one of top or bottom.
Horizontal anchor: choose exactly one of left or right.
Size keys width and height are required strings.
color is optional and useful for debugging hit zones.

WindowDragConfig example

Window props

Dimensions and position props are bindable and use px strings. You can style both the shell and content layers.

Prop	Type	Default	Required	Description
id	string	-	Yes	Unique id for registration and stacking order.
context	{ mouseContext, windowContext, desktop }	-	Yes	Context provided by WindowManager snippet.
children	Snippet	undefined	No	Window content rendered inside the managed window shell.
windowDragRegions	WindowDragConfig[]	[]	No	Absolute drag target regions inside the window.
resizable	boolean	true	No	Enable or disable all edge and corner resize handles.
resizeWhenInactive	boolean	false	No	Allow resize handles on inactive windows.
width / height	string (px)	300px	No	Current dimensions. Bindable.
left / top	string (px)	100px	No	Current position relative to manager desktop. Bindable.
minWidth / minHeight	number	300	No	Minimum window dimensions during resize.
innerStyle / outerStyle	string	undefined	No	Inline style hooks for interior or shell.
innerClassName / outerClassName	string	undefined	No	Class hooks for interior or shell.

Lifecycle callbacks

React to active state, drag events, and resize events. Useful for syncing layout state to your own stores.

onActiveStateChanged

Payload: boolean

Fires when this window becomes active/inactive.

onDragStart

Payload: { top: string, left: string }

Fires when drag begins on this window.

onDragEnd

Payload: { top: string, left: string }

Fires when drag finishes.

onResizeStart

Payload: { width: string, height: string }

Fires when any edge/corner resize starts.

onResizeEnd

Payload: { width: string, height: string }

Fires when resize finishes.

Callback example

Styling and behavior

Drag regions

Dragging is opt-in. Define one or more absolute regions to control where users can grab the window.

Resize handles

All four edges and four corners are supported. Touch and mouse are both wired through the same manager.

Shell vs content

Use outerStyle/outerClassName for shadows and chrome, and innerStyle/innerClassName for content.

Window stacking

Active windows are promoted to the front automatically. Iframe focus is detected and translated into window activation.

Exports

WindowManager, Window
MouseContext, WindowContext
INACTIVE_MOUSE_ID
WindowDragConfig, WindowPosition, WindowDimensions, ActualWindowProps