@gfazioli/mantine-window

A Mantine extension that renders draggable, resizable floating windows with keyboard resizing, persistent state, drag bounds, an axis lock, collapsible content and z-index management. Includes a WindowGroup compound component with layout presets, and a headless useDragResize hook that brings the same drag and resize to any element.

Version

v3.4.1

Changelog

View the Changelog

Source

View source code

Package

@gfazioli/mantine-window

Mantine Extensions

Docs

Edit this page

Built by

Giovambattista Fazioli (@gfazioli)

License

MIT

Support

Become a sponsor

Upgrading from an older major version? See the Upgrade guide for breaking changes and step-by-step migration instructions.

Installation

yarn add @gfazioli/mantine-window

After installation import package styles at the root of your application:

import '@gfazioli/mantine-window/styles.css';

You can import styles within a layer @layer mantine-window by importing @gfazioli/mantine-window/styles.layer.css file.

import '@gfazioli/mantine-window/styles.layer.css';

Comparison with Mantine core FloatingWindow

Since version 9.0, Mantine core ships a first-party FloatingWindow component, built on the headless use-floating-window hook. The basics overlap — a draggable, resizable surface with size limits and gesture callbacks — but the two make different trade-offs.

Capability	Window	Core FloatingWindow
Window chrome Title bar with close, collapse and a tools menu, in macOS or Windows order (controlsPosition, controlsOrder), plus opened / onClose — core is a bare Paper you fill yourself
Resize from every edge and corner Eight handles, resizable both / horizontal / vertical, fullSizeResizeHandles for full-length edges — core's single FloatingWindow.ResizeHandle grows the window right and down
Sizing in px, vw, vh and % For position, size, min / max and drag bounds — other units such as rem are not converted — core works in px
Responsive values Position, size, min / max, radius and shadow accept Mantine breakpoint maps
Confined to a container withinPortal={false} positions the window inside its parent and keeps it there — core is always position: fixed
Custom drag bounds dragBounds limits the window to any rectangle, in any unit — core can keep it inside the viewport (constrainToViewport, constrainOffset)
Interactive content left alone A press on an input, a button, a link or a data-no-window-drag region never starts a drag — core drags from the whole window unless you narrow it with dragHandleSelector / excludeDragHandleSelector
Collapse collapsable, also by double-clicking the header
Stacking and layouts Click to bring a window to the front; Window.Group adds snap, fill, columns, rows and tile layouts, collapse / close all, and z-index strategies
Persistence persistState keeps position and size in localStorage across reloads
Scrollable content Content is wrapped in a ScrollArea unless withScrollArea={false}
Drag and resize, mouse and touch Both — on a touch screen Window also lets a swipe scroll overflowing content, moves each window only with the finger that pressed it, and enlarges its handles and buttons
Stays on screen when the boundary shrinks keepInBounds moves the window back inside, and shrinks it to fit, when a phone rotates or the viewport or container gets smaller — core re-clamps when the window itself changes size
Min and max size minWidth / maxWidth / minHeight / maxHeight here, dimensions in core
Position from code Window: controlled x, y, width and height — core: initialPosition and setPositionRef
Gesture callbacks Both: onPositionChange and onSizeChange on every frame, plus onDragStart / onDragEnd and onResizeStart / onResizeEnd at the edges of a gesture
Turn dragging or resizing off draggable / resizable none here — enabled, or no resize handle, in core
Lock dragging to one axis axis x or y on both — Window's draggable also sets where you grab it (window, header or both)
Keyboard resizing Arrow keys and Home / End to the min / max size, on a role="separator" handle with aria-valuenow — Window adds Shift for a bigger step, configurable steps (resizeStep, resizeShiftStep) and the width × height as aria-valuetext on its corner
Headless hook use-floating-window makes any element draggable — useDragResize makes it draggable and resizable from any edge or corner, with the units, bounds, axis lock and keyboard resizing of Window

When to use which. Reach for the core FloatingWindow for a light draggable panel you style yourself — a floating toolbar, a chat box, a picture-in-picture player — when you would rather not add a dependency. Reach for Window when you want desktop-style windows: a title bar with its controls, resizing from any edge, sizes in viewport units or percentages that follow the breakpoints, a window confined to a container, position and size kept across reloads with persistState, and several windows arranged together with Window.Group. Reach for its headless hook when you want that same geometry on an element of your own.

Usage

The Window component allows you to create draggable and resizable windows within your application. It provides a familiar desktop-like experience for users. You can customize the appearance and behavior of the windows using various props.

Note:

Usually, you would want to use the Window component within a portal to avoid layout issues. However, if you want the window to be constrained within a specific container, you can set the withinPortal prop to false and the container should have position: relative style.

For example, in the demos below, the Window component is rendered relative to its parent container which has position: relative style.

Color

Title

Draggable

Resizable

Shadow

Radius

With border

With collapse button

With close button

With tools button

With scroll area

Controls position

Collapsed

Full size resize handles

import { Window, type WindowProps } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';
function Demo() {
  return (
    {/** In this demo, the Window is positioned relative to its parent container. Check the docs below to learn more about the "withinPortal" prop. */}
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        defaultX={0} defaultY={0}
        defaultWidth={320} defaultHeight={256}
        withinPortal={false}
        maxWidth={500}
        maxHeight={500}
        opened
        title="Hello, World! Hello, Mantiners! Say Hello to the Window component"
      >
        <Title order={4}>This is a window with data</Title>
      </Window>
    </Box>
  );
}

Controlled

You can control the open and close state of the Window component using the opened and onClose props. This allows you to manage the visibility of the window programmatically.

import { Window } from '@gfazioli/mantine-window';
import { Button, Stack, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [opened, { open, close }] = useDisclosure(false);

  return (
    <Stack pos="relative" style={{ width: '100%', height: 500 }}>
      <Button onClick={open}>Open window</Button>
      <Window title="Hello World" opened={opened} onClose={close} withinPortal={false}>
        <Title order={4}>This is a window</Title>
      </Window>
    </Stack>
  );
}

Position and Size

Set the initial position and size of the window using defaultX, defaultY, defaultWidth, and defaultHeight props. These values are used when the window is first rendered and can be modified by the user via drag and resize.

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Custom Position & Size"
        opened
        defaultX={150}
        defaultY={80}
        defaultWidth={350}
        defaultHeight={250}
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>Position: x=150, y=80</Title>
        <p>Size: 350 x 250</p>
      </Window>
    </Box>
  );
}

Controlled Position and Size

For full external control, use the x, y, width, and height props. When these are set, the component does not manage that value internally — your state drives it. Combine with onPositionChange and onSizeChange to sync state after user interactions.

You can also mix controlled and uncontrolled: for example, control only x and y while letting width and height remain uncontrolled via defaultWidth and defaultHeight.

X: 50

Y: 50

Width: 300

import { useState } from 'react';
import { Window } from '@gfazioli/mantine-window';
import { Box, Slider, Stack, Text, Title } from '@mantine/core';

function Demo() {
  const [x, setX] = useState(50);
  const [y, setY] = useState(50);
  const [width, setWidth] = useState(300);

  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Stack gap="xs" style={{ position: 'absolute', bottom: 10, left: 10, right: 10, zIndex: 100 }}>
        <Text size="sm">X: {x}</Text>
        <Slider value={x} onChange={setX} min={0} max={400} />
        <Text size="sm">Y: {y}</Text>
        <Slider value={y} onChange={setY} min={0} max={300} />
        <Text size="sm">Width: {width}</Text>
        <Slider value={width} onChange={setWidth} min={200} max={500} />
      </Stack>
      <Window
        title="Controlled"
        opened
        x={x}
        y={y}
        width={width}
        defaultHeight={180}
        onPositionChange={(pos) => { setX(pos.x); setY(pos.y); }}
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>Drag me or use sliders</Title>
      </Window>
    </Box>
  );
}

Within Portal vs Container

The withinPortal prop controls how the window is positioned. When withinPortal={true} (default), the window uses fixed positioning relative to the viewport. When withinPortal={false}, it uses absolute positioning relative to its parent container.

Fixed positioning (withinPortal=true):

Window stays in place when scrolling
Positioned relative to the browser viewport
Best for modals and overlays

Absolute positioning (withinPortal=false):

Window is constrained within parent container
Parent must have position: relative
Window cannot be dragged or resized outside container boundaries
Best for embedded UI components

Container with position: relative

import { Window } from '@gfazioli/mantine-window';
import { Button, Group, Stack, Text, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [portalOpened, { open: openPortal, close: closePortal }] = useDisclosure(false);
  const [containerOpened, { open: openContainer, close: closeContainer }] = useDisclosure(false);

  return (
    <>
      <Group mb="md">
        <Button onClick={openPortal}>Open in Portal (Fixed)</Button>
        <Button onClick={openContainer}>Open in Container (Relative)</Button>
      </Group>

      {/* Window with withinPortal={true} (default) - fixed positioning */}
      <Window 
        title="Fixed Window (Portal)" 
        opened={portalOpened} 
        onClose={closePortal}
        withinPortal={true}
        persistState={false}
        defaultX={100} defaultY={100}
      >
        <Stack p="md">
          <Title order={4}>Portal Window</Title>
          <Text size="sm">
            This window uses <strong>withinPortal=true</strong> (default).
            It is positioned fixed relative to the viewport and will stay in place even when scrolling.
          </Text>
        </Stack>
      </Window>

      {/* Container for relative window */}
      <Stack pos="relative" style={{ width: '100%', height: 400, border: '2px dashed gray' }} p="md">
        <Text c="dimmed" size="sm">Container with position: relative</Text>

        {/* Window with withinPortal={false} - absolute positioning */}
        <Window
          title="Relative Window (Container)"
          opened={containerOpened}
          onClose={closeContainer}
          withinPortal={false}
          persistState={false}
          defaultX={0} defaultY={0}
          defaultWidth={400} defaultHeight={300}
        >
          <Stack p="md">
            <Title order={4}>Container Window</Title>
            <Text size="sm">
              This window uses <strong>withinPortal=false</strong>.
              It is positioned absolute relative to its parent container and cannot be dragged or resized outside the container boundaries.
            </Text>
          </Stack>
        </Window>
      </Stack>
    </>
  );
}

Unit Types

Position and size props support three unit types:

Pixels (number): Fixed pixel values, e.g. defaultX={100}
Viewport units (string): vw for viewport width, vh for viewport height, e.g. defaultX="10vw"
Percentages (string): Relative to the reference container, e.g. defaultX="20%"

Understanding Unit References:

vw/vh: Always relative to the browser viewport, regardless of withinPortal setting
%: With withinPortal={true} (default) relative to the viewport; with withinPortal={false} relative to the parent container
Pixels: Always fixed, regardless of withinPortal setting

You can mix different unit types freely on the same component.

import { Window } from '@gfazioli/mantine-window';
import { Box, Stack, Text, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500, border: '2px dashed gray' }}>
      {/* Pixels */}
      <Window
        title="Pixels"
        opened
        defaultX={10}
        defaultY={10}
        defaultWidth={200}
        defaultHeight={180}
        persistState={false}
        withinPortal={false}
      >
        <Stack gap="xs">
          <Text size="sm"><strong>defaultX:</strong> 10</Text>
          <Text size="sm"><strong>defaultWidth:</strong> 200</Text>
        </Stack>
      </Window>

      {/* Percentages */}
      <Window
        title="Percentages"
        opened
        defaultX="40%"
        defaultY={10}
        defaultWidth={200}
        defaultHeight={180}
        persistState={false}
        withinPortal={false}
      >
        <Stack gap="xs">
          <Text size="sm"><strong>defaultX:</strong> "40%"</Text>
          <Text size="sm">Relative to container</Text>
        </Stack>
      </Window>

      {/* Percentages */}
      <Window
        title="Mixed"
        opened
        defaultX={10}
        defaultY="55%"
        defaultWidth="60%"
        defaultHeight={150}
        persistState={false}
        withinPortal={false}
      >
        <Stack gap="xs">
          <Text size="sm"><strong>defaultY:</strong> "55%"</Text>
          <Text size="sm"><strong>defaultWidth:</strong> "60%"</Text>
          <Text size="sm">Mix px, vw/vh, and % freely</Text>
        </Stack>
      </Window>
    </Box>
  );
}

Responsive

All dimension and position props support responsive values using Mantine breakpoints. Pass an object with breakpoint keys (base, xs, sm, md, lg, xl) to change values at different screen sizes.

This also applies to minWidth, maxWidth, minHeight, maxHeight, radius, and shadow.

import { Window } from '@gfazioli/mantine-window';
import { Box, Stack, Text, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Responsive Window"
        opened
        defaultX={{ base: 10, md: 50 }}
        defaultY={20}
        defaultWidth={{ base: 280, sm: 350, md: 450 }}
        defaultHeight={{ base: 200, md: 300 }}
        minWidth={{ base: 200, md: 300 }}
        radius={{ base: 'sm', md: 'lg' }}
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>Responsive Props</Title>
        <Stack gap="xs">
          <Text size="sm">
            <strong>defaultWidth:</strong>{' '}
            {'{ base: 280, sm: 350, md: 450 }'}
          </Text>
          <Text size="sm">
            <strong>defaultHeight:</strong>{' '}
            {'{ base: 200, md: 300 }'}
          </Text>
          <Text size="sm">
            <strong>minWidth:</strong>{' '}
            {'{ base: 200, md: 300 }'}
          </Text>
          <Text size="sm">
            <strong>radius:</strong>{' '}
            {'{ base: "sm", md: "lg" }'}
          </Text>
          <Text size="sm" c="dimmed" mt="xs">
            Resize your browser to see values change at breakpoints.
          </Text>
        </Stack>
      </Window>
    </Box>
  );
}

Min/Max Size Constraints

Control the minimum and maximum dimensions during resize operations using minWidth, minHeight, maxWidth, and maxHeight props. These support all unit types (pixels, viewport units, percentages) and responsive breakpoint objects.

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Constrained Resize"
        opened
        defaultX={50} defaultY={50}
        defaultWidth={400} defaultHeight={300}
        minWidth={300}
        minHeight={200}
        maxWidth={600}
        maxHeight={450}
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>Try resizing this window</Title>
        <p>Min: 300x200px</p>
        <p>Max: 600x450px</p>
      </Window>
    </Box>
  );
}

You can mix different unit types for constraints — for example, a fixed pixel minimum with a viewport-based maximum:

import { Window } from '@gfazioli/mantine-window';
import { Button, Stack, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [opened, { open, close }] = useDisclosure(false);

  return (
    <>
      <Button onClick={open}>Open window</Button>
      <Window
        title="Mixed Unit Constraints"
        opened={opened}
        onClose={close}
        defaultX={50} defaultY={50}
        defaultWidth={400} defaultHeight={350}
        minWidth={300}
        minHeight="15vh"
        maxWidth="60vw"
        maxHeight={600}
        persistState={false}
      >
        <Title order={4}>Mixed Units</Title>
        <Stack gap="sm">
          <p>
            <strong>Min Width:</strong> 300px (fixed)
          </p>
          <p>
            <strong>Min Height:</strong> 15vh (viewport-based)
          </p>
          <p>
            <strong>Max Width:</strong> 60vw (viewport-based)
          </p>
          <p>
            <strong>Max Height:</strong> 600px (fixed)
          </p>
        </Stack>
      </Window>
    </>
  );
}

Drag Boundaries

Restrict the draggable area of the window using the dragBounds prop. This ensures the window stays within specific boundaries. The dragBounds object accepts minX, maxX, minY, and maxY values, each supporting pixels, viewport units, and percentages.

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Bounded Dragging"
        opened
        defaultX={100} defaultY={50}
        defaultWidth={400} defaultHeight={300}
        dragBounds={{
          minX: 50,
          maxX: 500,
          minY: 50,
          maxY: 400,
        }}
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>Try dragging this window</Title>
        <p>It can only move within specific bounds:</p>
        <p>X: 50-500, Y: 50-400</p>
      </Window>
    </Box>
  );
}

Combine different unit types (pixels, viewport units, percentages) for drag boundaries to create flexible constraints:

import { Window } from '@gfazioli/mantine-window';
import { Button, Stack, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [opened, { open, close }] = useDisclosure(false);

  return (
    <>
      <Button onClick={open}>Open window</Button>
      <Window
        title="Mixed Unit Drag Bounds"
        opened={opened}
        onClose={close}
        defaultX={50} defaultY="10vh"
        defaultWidth={400} defaultHeight={300}
        dragBounds={{
          minX: 50,
          maxX: '80vw',
          minY: '10vh',
          maxY: 450,
        }}
        persistState={false}
      >
        <Title order={4}>Mixed Unit Boundaries</Title>
        <Stack gap="sm">
          <p>
            <strong>Min X:</strong> 50px (fixed)
          </p>
          <p>
            <strong>Max X:</strong> 80vw (viewport-based)
          </p>
          <p>
            <strong>Min Y:</strong> 10vh (viewport-based)
          </p>
          <p>
            <strong>Max Y:</strong> 450px (fixed)
          </p>
          <p>Mix different unit types for flexible boundaries!</p>
        </Stack>
      </Window>
    </>
  );
}

Axis Lock

Set axis="x" or axis="y" to restrict dragging to one direction: a window that slides along a dock, a panel that only moves up and down. The locked coordinate stays where the gesture started, while the free one is still kept inside the viewport, the container or dragBounds.

Only the user's drag is locked. A controlled x / y, the layouts of the tools menu and of Window.Group still move the window anywhere.

import { Window } from '@gfazioli/mantine-window';
import { Box, Text } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title='axis="x"'
        opened
        axis="x"
        defaultX={20}
        defaultY={20}
        defaultWidth={260}
        defaultHeight={160}
        withinPortal={false}
      >
        <Text size="sm">Drag me: I only slide left and right.</Text>
      </Window>

      <Window
        title='axis="y"'
        opened
        axis="y"
        defaultX={20}
        defaultY={220}
        defaultWidth={260}
        defaultHeight={160}
        withinPortal={false}
      >
        <Text size="sm">Drag me: I only slide up and down.</Text>
      </Window>
    </Box>
  );
}

Touch Screens and Small Boundaries

On a phone or a tablet, a window behaves as a finger expects:

A swipe on content that overflows scrolls it, because a finger has no wheel. A swipe on the title bar, or on content that fits, drags the window as before. The mouse is unchanged: it still drags from anywhere and scrolls with the wheel.
Each window follows only the finger that pressed it, so a second finger resting on another window does not drag that one too.
The resize handles and the title-bar buttons get bigger hit areas on a coarse pointer, and the buttons show their glyphs, since there is no hover to reveal them.

keepInBounds (on by default) keeps every window reachable inside its boundary, the viewport or its container:

When the boundary is measured, and whenever it or the window changes size (a phone rotating, a browser window or a container getting narrower, a collapsed window opening), a window that sticks out moves back inside it, and one larger than the boundary shrinks to fit. A collapsed window keeps its expanded height until it opens.
dragBounds can only narrow the boundary: bounds written for a wide screen no longer let a window out of a phone's.
Resizing with the pointer stops at the boundary, the viewport included, as keyboard resizing does.

Set keepInBounds={false} for the 3.3 behavior, for example to let a window hide partly off-screen through dragBounds. Moves made from code (a controlled x / y, the layouts) are applied as given: only a later change in the size of the boundary or of the window fits them again.

Container width: 100%

keepInBounds

import { Window } from '@gfazioli/mantine-window';
import { Box, Group, Slider, Stack, Switch, Text } from '@mantine/core';
import { useState } from 'react';

const lines = Array.from({ length: 12 }, (_, i) => `Line ${i + 1}: swipe me on a phone`);

function Demo() {
  const [width, setWidth] = useState(100);
  const [keepInBounds, setKeepInBounds] = useState(true);

  return (
    <Stack>
      <Group grow align="end">
        <Stack gap={4}>
          <Text size="sm">Container width: {width}%</Text>
          <Slider value={width} onChange={setWidth} min={30} max={100} label={null} />
        </Stack>
        <Switch
          label="keepInBounds"
          checked={keepInBounds}
          onChange={(event) => setKeepInBounds(event.currentTarget.checked)}
        />
      </Group>

      <Box
        pos="relative"
        h={400}
        w={`${width}%`}
        style={{ border: '2px dashed var(--mantine-color-default-border)' }}
      >
        <Window
          title="Shrink my container"
          opened
          withinPortal={false}
          keepInBounds={keepInBounds}
          defaultX={220}
          defaultY={60}
          defaultWidth={360}
          defaultHeight={240}
        >
          <Text size="sm" mb="xs">
            Narrow the container: the window moves back inside it, and shrinks once it is wider.
          </Text>
          {lines.map((line) => (
            <Text key={line} size="sm" c="dimmed">
              {line}
            </Text>
          ))}
        </Window>
      </Box>
    </Stack>
  );
}

Centered Window

Create a centered, fixed window that cannot be moved or resized by combining position/size props with resizable="none" and draggable="none".

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Centered Window"
        opened
        defaultX={190} defaultY={100}
        defaultWidth={420} defaultHeight={300}
        resizable="none"
        draggable="none"
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>Centered, fixed window</Title>
        <p>This window is centered and cannot be moved or resized</p>
      </Window>
    </Box>
  );
}

Disable Collapsing

Prevent the window from being collapsed by setting collapsable={false}. This removes the collapse functionality, including the double-click handler on the header.

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="No Collapsable"
        opened
        defaultX={50} defaultY={50}
        defaultWidth={400} defaultHeight={300}
        collapsable={false}
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>This window cannot be collapsed</Title>
        <p>Double-clicking the header will not collapse the window</p>
      </Window>
    </Box>
  );
}

Disable ScrollArea

By default, the window content is wrapped in a ScrollArea component. Set withScrollArea={false} to disable it — content that overflows will be clipped instead of scrollable. This is useful when your content already provides its own scrolling mechanism or when the ScrollArea interferes with the inner layout.

import { Window } from '@gfazioli/mantine-window';
import { Box, Text, Title } from '@mantine/core';

function Demo() {
  const lines = Array.from({ length: 10 }, (_, i) =>
    `Line ${i + 1}: Lorem ipsum dolor sit amet`
  );

  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      {/* Default: ScrollArea wraps content — overflow is scrollable */}
      <Window
        title="With ScrollArea (default)"
        opened
        defaultX={20} defaultY={20}
        defaultWidth={300} defaultHeight={200}
        persistState={false}
        withinPortal={false}
      >
        <Title order={5}>Same content</Title>
        {lines.map((line, i) => (
          <Text key={i} size="sm">{line}</Text>
        ))}
      </Window>

      {/* withScrollArea={false}: no scroll wrapper — overflow is clipped */}
      <Window
        title="Without ScrollArea"
        opened
        defaultX={350} defaultY={20}
        defaultWidth={300} defaultHeight={200}
        withScrollArea={false}
        persistState={false}
        withinPortal={false}
      >
        <Title order={5}>Same content</Title>
        {lines.map((line, i) => (
          <Text key={i} size="sm">{line}</Text>
        ))}
      </Window>
    </Box>
  );
}

Controls Position

The window title bar buttons (close, collapse, tools) default to the left side (macOS style). Set controlsPosition="right" to move them to the right side (Windows style). The button order is automatically reversed when positioned on the right — close moves to the far right, matching platform conventions.

For full control over button ordering, use the controlsOrder prop with an array of 'close', 'collapse', and 'tools' in your desired sequence. When controlsOrder is set, it overrides the automatic ordering.

import { Window } from '@gfazioli/mantine-window';
import { Box, Text } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      {/* macOS style: close, collapse, tools on the left (default) */}
      <Window
        title="macOS style (default)"
        opened
        defaultX={20} defaultY={20}
        defaultWidth={300} defaultHeight={150}
        controlsPosition="left"
        persistState={false}
        withinPortal={false}
      >
        <Text size="sm">Controls on the left — macOS style</Text>
      </Window>

      {/* Windows style: tools, collapse, close on the right (auto-reversed) */}
      <Window
        title="Windows style"
        opened
        defaultX={350} defaultY={20}
        defaultWidth={300} defaultHeight={150}
        controlsPosition="right"
        persistState={false}
        withinPortal={false}
      >
        <Text size="sm">Controls on the right — Windows style</Text>
        <Text size="sm" c="dimmed">Button order is automatically reversed</Text>
      </Window>

      {/* Custom order: tools first, then close */}
      <Window
        title="Custom order"
        opened
        defaultX={20} defaultY={220}
        defaultWidth={300} defaultHeight={150}
        controlsOrder={['tools', 'close', 'collapse']}
        persistState={false}
        withinPortal={false}
      >
        <Text size="sm">Custom order: tools, close, collapse</Text>
      </Window>
    </Box>
  );
}

Full Size Resize Handles

By default, resize handles (top, bottom, left, right) are centered and have a limited size (40px). Setting fullSizeResizeHandles={true} makes these handles span the entire width or height of the window edge, providing a larger interaction area.

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Full Size Resize Handles"
        opened
        defaultX={50} defaultY={50}
        defaultWidth={450} defaultHeight={350}
        fullSizeResizeHandles
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>Full Size Resize Handles</Title>
        <p>
          With <code>fullSizeResizeHandles</code> enabled, the side handles (top, bottom, left,
          right) span the entire width or height of the window.
        </p>
        <p>
          This makes it easier to resize from any edge, while corner handles (14x14px) remain for
          diagonal resizing.
        </p>
      </Window>
    </Box>
  );
}

Keyboard Resizing

Every resizable window has one resize handle that takes keyboard focus: the bottom-right corner, or the right edge when the window is collapsed or resizable="horizontal", or the bottom edge with resizable="vertical". One tab stop per window: the other seven handles stay pointer-only. With the handle focused:

the arrow keys move its edge by resizeStep pixels (default 10), and Shift + arrows by resizeShiftStep (default 50);
Home takes the window to its min size, and End to its max size.

No key ever takes the edge past the viewport or the container: there the edge wins over the min and max sizes, as it does when you resize with the pointer. End without a max size therefore stops at that edge.

The arrows are physical, as in the WAI-ARIA window splitter pattern: the window is placed with left and top, so in a right-to-left layout too the right arrow moves the right edge to the right.

The handle is a WAI-ARIA separator. Screen readers announce its name, resizeHandleLabel (default 'Resize window'), and its value: the width, or the height on the bottom edge, between aria-valuemin and aria-valuemax. On the corner, which changes both, aria-valuetext reads the width × height. While it has keyboard focus the handle is drawn in the primary color and the window is outlined.

Each key press is a complete resize gesture: it brings the window to the front, fires onResizeStart, onSizeChange and onResizeEnd like a pointer resize, and is saved by persistState. Set withKeyboardResize={false} to keep every handle pointer-only.

Resize step

Resize shift step

Resizable

With keyboard resize

import { Window } from '@gfazioli/mantine-window';
import { Box, Kbd, List, Text } from '@mantine/core';
function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Resize me from the keyboard"
        opened
        defaultX={20}
        defaultY={20}
        defaultWidth={360}
        defaultHeight={260}
        withinPortal={false}

      >
        <Text size="sm">
          Press <Kbd>Tab</Kbd> until the resize handle is focused, then:
        </Text>
        <List size="sm" mt="xs">
          <List.Item>
            <Kbd>←</Kbd> <Kbd>→</Kbd> <Kbd>↑</Kbd> <Kbd>↓</Kbd> resize by the step
          </List.Item>
          <List.Item>
            <Kbd>Shift</Kbd> + arrows resize by the Shift step
          </List.Item>
          <List.Item>
            <Kbd>Home</Kbd> / <Kbd>End</Kbd> go to the min / max size
          </List.Item>
        </List>
      </Window>
    </Box>
  );
}

Persistence

Enable state persistence to save the window's position and size in localStorage by setting persistState={true} (default is false). When enabled, the window will remember its position and size across page refreshes.

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="With Persistence"
        id="persistent-window-demo"
        opened
        defaultX={50} defaultY={50}
        defaultWidth={400} defaultHeight={300}
        persistState
        withinPortal={false}
      >
        <Title order={4}>Position, size, and collapsed state are saved in localStorage</Title>
        <p>Move, resize, or collapse/expand this window, then refresh the page</p>
        <p>The window will remember its last position, size, and collapsed state</p>
      </Window>
    </Box>
  );
}

Callbacks

Use onPositionChange and onSizeChange callbacks to respond to window movements and resize operations. These callbacks receive the current position or size as pixel values.

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="With Callbacks"
        opened
        defaultX={50} defaultY={50}
        defaultWidth={400} defaultHeight={300}
        persistState={false}
        withinPortal={false}
        onPositionChange={(pos) => {
          // eslint-disable-next-line no-console
          console.log('Position changed:', pos);
        }}
        onSizeChange={(size) => {
          // eslint-disable-next-line no-console
          console.log('Size changed:', size);
        }}
      >
        <Title order={4}>Open console to see callbacks</Title>
        <p>Move or resize this window to trigger callbacks</p>
      </Window>
    </Box>
  );
}

Drag and Resize Lifecycle

onPositionChange and onSizeChange fire continuously, on every frame of a gesture. Four more callbacks mark its edges instead: onDragStart, onDragEnd, onResizeStart and onResizeEnd. They mirror the set that Mantine core's FloatingWindow exposes.

The edges are what make a gesture composable. Persist the layout once, on end, instead of debouncing every frame by hand; pause an expensive child, an iframe or a video while the user drags and resume after; show a snap guide or a dimension badge only while the gesture runs; record a single undo entry per gesture rather than one per pixel.

Each start is paired with exactly one end. A press on a resize handle, on an interactive child (input, button, link, …) or on a data-no-window-drag region does not open a drag, so no onDragStart fires there either — and a resize never emits drag callbacks, nor the other way round. Unmounting mid-gesture still fires the matching end, so a paused child is never left paused.

import { useState } from 'react';
import { Window } from '@gfazioli/mantine-window';
import { Badge, Box, Code, Group, Stack, Text } from '@mantine/core';

function Demo() {
  const [gesture, setGesture] = useState<'idle' | 'dragging' | 'resizing'>('idle');
  const [during, setDuring] = useState(0);
  const [atEnd, setAtEnd] = useState(0);

  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Drag or resize me"
        opened
        defaultX={50} defaultY={50}
        defaultWidth={420} defaultHeight={300}
        persistState={false}
        withinPortal={false}
        // Continuous: fires on every frame of the gesture
        onPositionChange={() => setDuring((n) => n + 1)}
        onSizeChange={() => setDuring((n) => n + 1)}
        // Lifecycle: one call each, at the edges of the gesture
        onDragStart={() => setGesture('dragging')}
        onDragEnd={() => { setGesture('idle'); setAtEnd((n) => n + 1); }}
        onResizeStart={() => setGesture('resizing')}
        onResizeEnd={() => { setGesture('idle'); setAtEnd((n) => n + 1); }}
      >
        <Stack gap="md" p="xs">
          <Group>
            <Text size="sm">State:</Text>
            <Badge color={gesture === 'idle' ? 'gray' : 'blue'}>{gesture}</Badge>
          </Group>

          <Text size="sm">
            Writes if you persisted on every change: <Code>{during}</Code>
          </Text>
          <Text size="sm">
            Writes if you persisted on end only: <Code>{atEnd}</Code>
          </Text>

          <Text size="xs" c="dimmed">
            Both numbers describe the same gesture. The second one is why the lifecycle
            callbacks exist.
          </Text>
        </Stack>
      </Window>
    </Box>
  );
}

Multiple Windows

You can render multiple windows in the same container. Each window maintains its own z-index and can be brought to the front by clicking on it. Use unique id props to ensure proper state persistence.

import { Window } from '@gfazioli/mantine-window';
import { Box, Title } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 500 }}>
      <Window
        title="Window 1"
        id="demo-window-1"
        opened
        defaultX={20} defaultY={20}
        defaultWidth={300} defaultHeight={250}
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>First Window</Title>
        <p>Click on a window to bring it to front</p>
      </Window>
      <Window
        title="Window 2"
        id="demo-window-2"
        opened
        defaultX={180} defaultY={80}
        defaultWidth={300} defaultHeight={250}
        persistState={false}
        withinPortal={false}
      >
        <Title order={4}>Second Window</Title>
        <p>Click on a window to bring it to front</p>
      </Window>
    </Box>
  );
}

Context Menu

Mantine 9.3 introduces the Menu.ContextMenu component: attach desktop-style right-click actions to any surface. Inside a Window it completes the desktop metaphor — and in this demo the actions are real: duplicate the window or close it, with the windows rendered dynamically from state.

import { useState } from 'react';
import { Window } from '@gfazioli/mantine-window';
import { Box, Button, Center, Menu, Text } from '@mantine/core';
import { IconCopy, IconX } from '@tabler/icons-react';

type Pane = { id: number; x: number; y: number };

function Demo() {
  const [panes, setPanes] = useState<Pane[]>([{ id: 1, x: 40, y: 40 }]);
  const [nextId, setNextId] = useState(2);

  const openPane = (x: number, y: number) => {
    setPanes((current) => [...current, { id: nextId, x, y }]);
    setNextId((id) => id + 1);
  };

  const closePane = (id: number) => {
    setPanes((current) => current.filter((pane) => pane.id !== id));
  };

  return (
    <Box pos="relative" style={{ width: '100%', height: 480 }}>
      {panes.length === 0 && (
        <Center h="100%">
          <Button onClick={() => openPane(40, 40)}>Open a window</Button>
        </Center>
      )}

      {panes.map((pane) => (
        <Window
          key={pane.id}
          title={`Window ${pane.id}`}
          opened
          defaultX={pane.x}
          defaultY={pane.y}
          defaultWidth={320}
          defaultHeight={220}
          persistState={false}
          withinPortal={false}
          withScrollArea={false}
          onClose={() => closePane(pane.id)}
        >
          <Menu shadow="md" width={210} withArrow>
            <Menu.ContextMenu>
              <Box p="md" h="100%" style={{ userSelect: 'none' }}>
                <Text fw={600}>Right-click here</Text>
                <Text c="dimmed" size="sm" mt={4}>
                  The context menu actions really drive this window: duplicate it or close it.
                </Text>
              </Box>
            </Menu.ContextMenu>

            <Menu.Dropdown>
              <Menu.Label>Window {pane.id}</Menu.Label>
              <Menu.Item
                leftSection={<IconCopy size={14} />}
                onClick={() => openPane(pane.x + 48, pane.y + 48)}
              >
                Duplicate window
              </Menu.Item>
              <Menu.Divider />
              <Menu.Item
                color="red"
                leftSection={<IconX size={14} />}
                onClick={() => closePane(pane.id)}
              >
                Close window
              </Menu.Item>
            </Menu.Dropdown>
          </Menu>
        </Window>
      ))}
    </Box>
  );
}

Window Menu Bar

Mantine 9.4 ships a real Menubar component — a horizontal row of menus with full keyboard navigation (arrow keys move between top-level menus, and once one is open, moving to a sibling opens it immediately) and the WAI-ARIA menubar semantics. Dropped into a Window it completes the desktop-application metaphor. In this demo every entry drives the workspace for real: the File and Edit menus report the executed command in the status bar, while the View menu toggles the canvas grid and changes the layout density. Because the Window drag handler ignores interactive targets — and the menu triggers carry the menuitem role — the menu bar stays fully usable inside the draggable surface.

import { useState } from 'react';
import { Window } from '@gfazioli/mantine-window';
import { Box, Menu, Menubar, Paper, Stack, Text } from '@mantine/core';

const densities = { compact: 'xs', comfortable: 'sm', spacious: 'lg' } as const;

function Demo() {
  const [layers, setLayers] = useState(['Layer 1', 'Layer 2']);
  const [nextLayer, setNextLayer] = useState(3);
  const [lastAction, setLastAction] = useState<string | null>(null);
  const [showGrid, setShowGrid] = useState(true);
  const [density, setDensity] = useState<keyof typeof densities>('comfortable');

  const run = (label: string, fn?: () => void) => {
    fn?.();
    setLastAction(label);
  };

  return (
    <Box pos="relative" style={{ width: '100%', height: 520 }}>
      <Window
        title="Design Workspace"
        opened
        defaultX={30}
        defaultY={30}
        defaultWidth={460}
        defaultHeight={360}
        persistState={false}
        withinPortal={false}
        withScrollArea={false}
      >
        <Stack gap="sm" h="100%">
          {/* Mantine 9.4 Menubar — a real desktop-style menu bar with keyboard navigation */}
          <Menubar trigger="click">
            <Menubar.Menu width={240}>
              <Menubar.Target>File</Menubar.Target>
              <Menubar.Dropdown>
                <Menu.Item
                  rightSection={
                    <Text size="xs" c="dimmed">
                      ⌘N
                    </Text>
                  }
                  onClick={() =>
                    run('New layer', () => {
                      setLayers((current) => [...current, `Layer ${nextLayer}`]);
                      setNextLayer((n) => n + 1);
                    })
                  }
                >
                  New layer
                </Menu.Item>
                <Menu.Item
                  rightSection={
                    <Text size="xs" c="dimmed">
                      ⌘D
                    </Text>
                  }
                  onClick={() =>
                    run('Duplicate layer', () =>
                      setLayers((current) =>
                        current.length > 0
                          ? [...current, `${current[current.length - 1]} copy`]
                          : current
                      )
                    )
                  }
                >
                  Duplicate layer
                </Menu.Item>
                <Menu.Item onClick={() => run('Remove layer', () => setLayers((c) => c.slice(0, -1)))}>
                  Remove layer
                </Menu.Item>
                <Menu.Divider />
                <Menu.Item
                  rightSection={
                    <Text size="xs" c="dimmed">
                      ⌘E
                    </Text>
                  }
                  onClick={() => run('Export as PNG')}
                >
                  Export as PNG
                </Menu.Item>
              </Menubar.Dropdown>
            </Menubar.Menu>

            <Menubar.Menu width={220}>
              <Menubar.Target>Edit</Menubar.Target>
              <Menubar.Dropdown>
                <Menu.Item color="red" onClick={() => run('Clear all layers', () => setLayers([]))}>
                  Clear all layers
                </Menu.Item>
                <Menu.Item
                  onClick={() =>
                    run('Reset view', () => {
                      setShowGrid(true);
                      setDensity('comfortable');
                    })
                  }
                >
                  Reset view
                </Menu.Item>
              </Menubar.Dropdown>
            </Menubar.Menu>

            <Menubar.Menu width={220} closeOnItemClick={false}>
              <Menubar.Target>View</Menubar.Target>
              <Menubar.Dropdown>
                <Menu.Label>Canvas</Menu.Label>
                <Menu.CheckboxItem checked={showGrid} onChange={setShowGrid}>
                  Show grid
                </Menu.CheckboxItem>
                <Menu.Divider />
                <Menu.Label>Density</Menu.Label>
                <Menu.RadioGroup
                  value={density}
                  onChange={(value) => setDensity(value as keyof typeof densities)}
                >
                  <Menu.RadioItem value="compact">Compact</Menu.RadioItem>
                  <Menu.RadioItem value="comfortable">Comfortable</Menu.RadioItem>
                  <Menu.RadioItem value="spacious">Spacious</Menu.RadioItem>
                </Menu.RadioGroup>
              </Menubar.Dropdown>
            </Menubar.Menu>
          </Menubar>

          {/* The canvas reacts to every menu action */}
          <Box
            flex={1}
            p="sm"
            style={{
              overflow: 'auto',
              borderRadius: 'var(--mantine-radius-sm)',
              border: '1px solid var(--mantine-color-default-border)',
              backgroundImage: showGrid
                ? 'radial-gradient(var(--mantine-color-default-border) 1px, transparent 0)'
                : undefined,
              backgroundSize: '16px 16px',
            }}
          >
            {layers.length > 0 ? (
              <Stack gap={densities[density]}>
                {layers.map((layer, index) => (
                  <Paper key={index} withBorder p={densities[density]}>
                    {layer}
                  </Paper>
                ))}
              </Stack>
            ) : (
              <Text c="dimmed" size="sm" ta="center" py="lg">
                No layers — use File → New layer
              </Text>
            )}
          </Box>

          {/* Status bar: every menu command lands here */}
          <Text size="xs" c="dimmed">
            {lastAction ? `Last action: ${lastAction}` : 'Pick a command from the menu bar'}
          </Text>
        </Stack>
      </Window>
    </Box>
  );
}

Form Controls

A Window is a regular content surface: any interactive Mantine input works inside it and keeps its native behavior. In particular a searchable Select can be focused, typed into and filtered — the window only starts dragging when you grab a non-interactive area (or the header), so form fields never steal the drag and the drag never steals their focus. You can opt any custom region out of dragging with the data-no-window-drag attribute.

import { Window } from '@gfazioli/mantine-window';
import { Box, NumberInput, Select, Stack, TextInput } from '@mantine/core';

function Demo() {
  return (
    <Box pos="relative" style={{ width: '100%', height: 420 }}>
      <Window
        title="Profile settings"
        opened
        defaultX={30}
        defaultY={30}
        defaultWidth={360}
        defaultHeight={340}
        persistState={false}
        withinPortal={false}
      >
        <Stack gap="sm">
          <TextInput label="Display name" placeholder="Jane Doe" />
          {/* Searchable Select: focus, typing and filtering work while inside the Window */}
          <Select
            label="Favorite library"
            placeholder="Pick value"
            data={['React', 'Angular', 'Vue', 'Svelte']}
            searchable
          />
          <NumberInput label="Years of experience" placeholder="0" min={0} />
        </Stack>
      </Window>
    </Box>
  );
}

Window.Group

Wrap multiple windows in a Window.Group to enable coordinated window management. The group provides:

Coordinated z-index: Windows within a group share a stacking context
Layout presets: Snap, tile, and fill layouts via the green tools button in each window header
Global actions: Collapse all, expand all, close all

Each Window inside a Window.Group must have a unique id prop. The group defaults to withinPortal={false} (overridable via the withinPortal prop) and applies position: relative on its container.

import { Window } from '@gfazioli/mantine-window';
import { Title } from '@mantine/core';

function Demo() {
  return (
    <Window.Group style={{ width: '100%', height: 500 }}>
      <Window
        id="editor"
        title="Editor"
        opened
        defaultX={10}
        defaultY={10}
        defaultWidth={300}
        defaultHeight={250}
      >
        <Title order={4}>Editor window</Title>
        <p>Try the green button for layout options</p>
      </Window>
      <Window
        id="preview"
        title="Preview"
        opened
        defaultX={320}
        defaultY={10}
        defaultWidth={300}
        defaultHeight={250}
      >
        <Title order={4}>Preview window</Title>
      </Window>
      <Window
        id="console"
        title="Console"
        opened
        defaultX={10}
        defaultY={270}
        defaultWidth={610}
        defaultHeight={200}
      >
        <Title order={4}>Console window</Title>
      </Window>
    </Window.Group>
  );
}

Tools Button

The green tools button in the window header provides layout options. It is controlled by the withToolsButton prop (default: true) and is available on every window, even outside a Window.Group.

Without a Group, the menu shows only single-window actions:

Move & Resize: Snap left, snap right, snap top, snap bottom — positions the current window to fill half of the container or viewport
Fill: Maximizes the current window to fill the entire available area

Inside a Group, the menu also shows group-wide actions:

Arrange Columns / Rows: Distributes all visible windows in equal columns or rows
Tile: Arranges all visible windows in an automatic grid
Collapse all / Expand all: Collapses or expands all windows that have collapsable={true}. Windows with collapsable={false} are skipped.
Close all: Closes all windows in the group

The onLayoutChange callback on Window.Group notifies you when a group layout is applied.

Last layout applied:

none

import { useState } from 'react';
import { Window, type WindowLayout } from '@gfazioli/mantine-window';
import { Badge, Group, Stack, Text, Title } from '@mantine/core';

function Demo() {
  const [lastLayout, setLastLayout] = useState<WindowLayout | null>(null);

  return (
    <Stack gap="sm">
      <Group>
        <Text size="sm">Last layout applied:</Text>
        <Badge>{lastLayout ?? 'none'}</Badge>
      </Group>
      <Window.Group
        style={{ width: '100%', height: 500 }}
        defaultLayout="tile"
        onLayoutChange={setLastLayout}
      >
        <Window id="w1" title="Window 1" opened defaultX={10} defaultY={10} defaultWidth={250} defaultHeight={200}>
          <Title order={4}>Window 1</Title>
          <p>Use the green button to apply layouts</p>
        </Window>
        <Window id="w2" title="Window 2" opened defaultX={270} defaultY={10} defaultWidth={250} defaultHeight={200}>
          <Title order={4}>Window 2</Title>
        </Window>
        <Window id="w3" title="Window 3" opened defaultX={10} defaultY={220} defaultWidth={250} defaultHeight={200}>
          <Title order={4}>Window 3</Title>
        </Window>
        <Window id="w4" title="Window 4" opened defaultX={270} defaultY={220} defaultWidth={250} defaultHeight={200}>
          <Title order={4}>Window 4</Title>
        </Window>
      </Window.Group>
    </Stack>
  );
}

Layout Presets

Use defaultLayout to apply an initial layout when the group mounts. To control the layout externally, use the groupRef prop to access the group API and call applyLayout programmatically.

Layout

import { useRef, useState } from 'react';
import { Window, type WindowGroupContextValue, type WindowLayout } from '@gfazioli/mantine-window';
import { Select, Stack, Title } from '@mantine/core';

const layoutOptions = [
  { value: 'tile', label: 'Tile' },
  { value: 'arrange-columns', label: 'Columns' },
  { value: 'arrange-rows', label: 'Rows' },
];

function Demo() {
  const [layout, setLayout] = useState<string | null>('tile');
  const groupRef = useRef<WindowGroupContextValue>(null);

  return (
    <Stack gap="sm">
      <Select
        label="Layout"
        data={layoutOptions}
        value={layout}
        onChange={(value) => {
          setLayout(value);
          if (value) {
            groupRef.current?.applyLayout(value as WindowLayout);
          }
        }}
        w={200}
      />
      <Window.Group
        groupRef={groupRef}
        style={{ width: '100%', height: 450 }}
        defaultLayout="tile"
        onLayoutChange={(l) => setLayout(l)}
      >
        <Window id="lp-1" title="Window 1" opened>
          <Title order={4}>Window 1</Title>
        </Window>
        <Window id="lp-2" title="Window 2" opened>
          <Title order={4}>Window 2</Title>
        </Window>
        <Window id="lp-3" title="Window 3" opened>
          <Title order={4}>Window 3</Title>
        </Window>
      </Window.Group>
    </Stack>
  );
}

Dynamic Windows

Windows inside a Window.Group can be rendered dynamically from an array — for example via .map() over a piece of state. Layout presets and group actions wait until the registry is populated and the container is measured, so a layout triggered before all children have mounted is automatically deferred and flushed when everything is ready.

import { useState } from 'react';
import { Window } from '@gfazioli/mantine-window';
import { Button, Group, Title } from '@mantine/core';

function Demo() {
  const [ids, setIds] = useState<string[]>(['alpha', 'beta']);

  return (
    <>
      <Group mb="md">
        <Button
          onClick={() =>
            setIds((prev) => [...prev, String.fromCharCode(97 + prev.length)])
          }
        >
          Add window
        </Button>
        <Button color="red" onClick={() => setIds((prev) => prev.slice(0, -1))}>
          Remove last
        </Button>
      </Group>
      <Window.Group style={{ width: '100%', height: 500 }}>
        {ids.map((id, i) => (
          <Window
            id={`win_${id}`}
            key={`win_${id}`}
            title={`Window ${id}`}
            opened
            defaultX={20 + i * 40}
            defaultY={20 + i * 40}
            defaultWidth={300}
            defaultHeight={200}
          >
            <Title order={4}>Dynamic {id}</Title>
            <p>Click the green tools button to apply a layout preset.</p>
          </Window>
        ))}
      </Window.Group>
    </>
  );
}

Z-index Management

Both Window.Group and stand-alone Window expose z-index configuration via three props:

initialZIndex — starting value for the stacking context. Defaults to 200 when withinPortal is true, 1 otherwise.
maxZIndex — upper bound. When the counter would exceed this value it wraps back to initialZIndex, preventing unbounded escalation above modals or menus.
zIndexStrategy (Window.Group only) — how z-indexes are assigned when a window is focused or registered:
- 'increment' (default): a counter monotonically increases. Preserves legacy behavior. Combine with maxZIndex to keep values bounded.
- 'normalize': z-indexes are derived from the stacking order and always stay within initialZIndex .. initialZIndex + N - 1. Recommended for long-running applications or when Mantine modals and menus are used alongside.

increment (legacy)

normalize

Click each window in any order. With normalize, z-indexes always stay compact ({100..102}). With increment, the counter keeps growing unless maxZIndex is set.

import { useState } from 'react';
import { Window } from '@gfazioli/mantine-window';
import { SegmentedControl, Stack, Text, Title } from '@mantine/core';

function Demo() {
  const [strategy, setStrategy] = useState<'increment' | 'normalize'>('normalize');

  return (
    <Stack>
      <SegmentedControl
        value={strategy}
        onChange={(v) => setStrategy(v as 'increment' | 'normalize')}
        data={[
          { label: 'increment (legacy)', value: 'increment' },
          { label: 'normalize', value: 'normalize' },
        ]}
      />
      <Text size="sm" c="dimmed">
        Click each window in any order. With <code>normalize</code>, z-indexes always stay
        compact ({'{100..102}'}). With <code>increment</code>, the counter keeps growing
        unless <code>maxZIndex</code> is set.
      </Text>
      <Window.Group
        key={strategy}
        style={{ width: '100%', height: 500 }}
        zIndexStrategy={strategy}
        initialZIndex={100}
        maxZIndex={strategy === 'increment' ? 105 : undefined}
      >
        <Window id="z1" title="Alpha" opened defaultX={20} defaultY={20} defaultWidth={260} defaultHeight={180}>
          <Title order={5}>Alpha</Title>
        </Window>
        <Window id="z2" title="Beta" opened defaultX={80} defaultY={80} defaultWidth={260} defaultHeight={180}>
          <Title order={5}>Beta</Title>
        </Window>
        <Window id="z3" title="Gamma" opened defaultX={140} defaultY={140} defaultWidth={260} defaultHeight={180}>
          <Title order={5}>Gamma</Title>
        </Window>
      </Window.Group>
    </Stack>
  );
}

Headless Hook

useDragResize is the engine Window is built on, exported so you can put the same geometry on any element: a card, a sticky note, an image, a floating toolbar. Core's use-floating-window drags an element; this hook also resizes it, from any edge or corner.

import { useDragResize } from '@gfazioli/mantine-window';

function Note() {
  const { ref, position, size, getDragHandleProps, getResizeHandleProps } = useDragResize({
    boundary: 'parent',
    defaultSize: { width: 240, height: 160 },
  });

  return (
    <div
      ref={ref}
      {...getDragHandleProps()}
      style={{ position: 'absolute', left: position.x, top: position.y, ...size }}
    >
      Drag me
      <div {...getResizeHandleProps('bottomRight', { keyboard: true })} className="grip" />
    </div>
  );
}

The hook computes, and you render: put position on left / top and size on width / height, with position: fixed for boundary: 'viewport' (the default) or position: absolute in a positioned parent for boundary: 'parent'.

Options. Everything is optional.

position / defaultPosition and size / defaultSize: controlled or uncontrolled, in pixels, vw, vh or a percentage of the boundary. The defaults are those of Window: { x: 20, y: 100 } and 400 × 400.
minWidth, maxWidth, minHeight, maxHeight: the same units. The mins default to 250 and 100, like Window's.
boundary: 'viewport' or 'parent'. The element is kept inside it while dragging, and a parent also limits resizing.
dragBounds: a narrower rectangle for the position, in the same units.
axis: 'x' or 'y', to lock dragging to one direction.
keepInBounds: keeps the element inside the boundary. It moves back inside, and shrinks to fit, when the boundary is measured or changes size; dragBounds can only narrow the boundary; a pointer resize stops at the viewport edge. true by default.
resizeStep and resizeShiftStep: the keyboard steps, 10 and 50 pixels by default.
onPositionChange and onSizeChange, with pixel values, and onDragStart, onDragEnd, onResizeStart and onResizeEnd, at the edges of each gesture.

Returns.

ref: for the element that moves.
position and size: the current values, in pixels.
setPosition and setSize: move or resize it from code, in pixels.
isDragging and isResizing: true while a pointer gesture runs.
boundarySize: the size of the viewport or of the parent, 0 until it has been measured.
getDragHandleProps(): spread it on the area that starts a drag. A press on an input, a button, a link or a data-no-window-drag region never starts one, as in Window.
getResizeHandleProps(direction, options): spread it on a resize handle for 'top', 'right', 'bottom', 'left' or a corner such as 'bottomRight'. Pass { keyboard: true, label } to one handle to make it the focusable separator described in Keyboard Resizing.

Persistence, collapsing, stacking, the title bar and Window.Group stay in Window: the hook is only the geometry.

A plain Paper

Drag it anywhere, resize it from the right, the bottom or the corner.

300 × 190 at 40, 40

idle

import { useDragResize } from '@gfazioli/mantine-window';
import { Badge, Box, Code, Paper, Stack, Text } from '@mantine/core';

function Demo() {
  const { ref, position, size, isDragging, isResizing, getDragHandleProps, getResizeHandleProps } =
    useDragResize({
      boundary: 'parent',
      defaultPosition: { x: 40, y: 40 },
      defaultSize: { width: 300, height: 190 },
      minWidth: 200,
      minHeight: 150,
      maxWidth: '90%',
    });

  return (
    <Box pos="relative" h={420} bg="var(--mantine-color-default-hover)">
      <Paper
        ref={ref}
        withBorder
        shadow={isDragging ? 'xl' : 'sm'}
        p="md"
        {...getDragHandleProps()}
        style={{
          position: 'absolute',
          left: position.x,
          top: position.y,
          width: size.width,
          height: size.height,
          cursor: isDragging ? 'grabbing' : 'grab',
        }}
      >
        <Stack gap="xs">
          <Text fw={600}>A plain Paper</Text>
          <Text size="sm">
            Drag it anywhere, resize it from the right, the bottom or the corner.
          </Text>
          <Code>
            {Math.round(size.width)} × {Math.round(size.height)} at {Math.round(position.x)},{' '}
            {Math.round(position.y)}
          </Code>
          <Badge variant="light" color={isDragging || isResizing ? 'blue' : 'gray'}>
            {isDragging ? 'dragging' : isResizing ? 'resizing' : 'idle'}
          </Badge>
        </Stack>

        <Box
          {...getResizeHandleProps('right')}
          style={{
            position: 'absolute',
            top: 0,
            right: 0,
            bottom: 0,
            width: 8,
            cursor: 'ew-resize',
          }}
        />
        <Box
          {...getResizeHandleProps('bottom')}
          style={{
            position: 'absolute',
            left: 0,
            right: 0,
            bottom: 0,
            height: 8,
            cursor: 'ns-resize',
          }}
        />
        <Box
          {...getResizeHandleProps('bottomRight', { keyboard: true, label: 'Resize card' })}
          className="mantine-focus-auto"
          style={{
            position: 'absolute',
            right: 2,
            bottom: 2,
            width: 16,
            height: 16,
            cursor: 'nwse-resize',
            borderRadius: 2,
            background:
              'linear-gradient(135deg, transparent 50%, var(--mantine-color-dimmed) 50%, var(--mantine-color-dimmed) 60%, transparent 60%, transparent 75%, var(--mantine-color-dimmed) 75%, var(--mantine-color-dimmed) 85%, transparent 85%)',
          }}
        />
      </Paper>
    </Box>
  );
}

Styles API

Window supports Styles API, you can add styles to any inner element of the component with classNames prop. Follow Styles API documentation to learn more.

Component Styles API

Hover over selectors to highlight corresponding elements

/*
 * Hover over selectors to apply outline styles
 *
 */

HIGHLIGHTS

MANTINE

APPS

OTHER MANTINE EXTENSIONS

Sponsors