@crustack/resizable

Headless components for creating resizable elements.

Quick Start

Define the resizable components

resizable.tsx

'use client'
import { defineResizable } from '@crustack/resizable'

const resizable = defineResizable()

Create a resizable element with the `Root` component.

You should provide boundary constraints like minHeight, maxHeight, minWidth, and maxWidth to control resizing behavior.

export function MyComponent() {
  const [size, setSize] = useState<Size>({ width: '50%', height: '300px' })

  return (
    <resizable.Root
      size={size}
      onResize={setSize}
      className="relative max-h-full min-h-8 min-w-8 max-w-full"
    >
      Resizable Content
    </resizable.Root>
  )
}

Add Resize Handles with the `Handle` component.

The Handle component lets you add draggable handles for resizing.

The ratio prop defines which direction the resizing occurs (e.g., horizontally, vertically, or both).
The cursor prop defines the cursor style during the resize operation and ensures consistency by applying it to both the handle and the body when the handle is active.

Here's how to add handles for different sides and corners:

export function MyComponent() {
  const [size, setSize] = useState<Size>({ width: '50%', height: '300px' })

  return (
    <resizable.Root
      size={size}
      onResize={setSize}
      className="relative max-h-full min-h-8 min-w-8 max-w-full"
    >
      <div>Resizable Content</div>

      {/* Right handle */}
      <resizable.Handle
        ratio={{ width: 1, height: 0 }}
        cursor="col-resize"
        className="absolute right-0 top-1/2 size-4 -translate-y-1/2 translate-x-1/2 bg-slate-200 data-[active]:bg-teal-500"
      />
      {/* Bottom handle */}
      <resizable.Handle
        ratio={{ width: 0, height: 1 }}
        cursor="row-resize"
        className="absolute bottom-0 left-1/2 size-4 -translate-x-1/2 translate-y-1/2 bg-slate-200 data-[active]:bg-teal-500"
      />
      {/* Bottom-Right handle */}
      <resizable.Handle
        ratio={{ width: 1, height: 1 }}
        cursor="move"
        className="absolute bottom-0 right-0 size-4 translate-x-1/2 translate-y-1/2 bg-slate-200 data-[active]:bg-teal-500"
      />
    </resizable.Root>
  )
}

Examples

This example demonstrates how to build a Left aligned resizable sidebar.

export const Sidebar = () => {
  const [width, setWidth] = useState(200)

  return (
    <resizable.Root
      // use the width only
      size={{ width }}
      onResize={({ width }) => setWidth(width)}
      // place the sidebar and define its bounds
      className="relative h-screen min-w-24 max-w-[50vw]"
      // skip rendering the default div, forward all props to the child instead
      asChild
    >
      <nav>
        <resizable.Handle
          // can resize the width from the right side
          ratio={{ width: 1, height: 0 }}
          // position & style the handle
          className="absolute right-0 top-0 z-10 h-full w-1.5 translate-x-1/2 overflow-auto transition hover:bg-teal-700/30 data-[active]:bg-teal-700/50"
          // cursor style
          cursor="col-resize"
        />
        <ul>
          <li>...</li>
          <li>...</li>
          <li>...</li>
        </ul>
      </nav>
    </resizable.Root>
  )
}

Building off the Left aligned Sidebar example,we will modify the handle's position and the resize behavior to create a Right-aligned sidebar.

By default, if you place the handle on the left side of the Root, resizing behaves inversely to what you'd expect. To fix this, we'll use the ratio prop to invert the width calculations.

export const Sidebar = () => {
  const [width, setWidth] = useState(200)

  return (
    <resizable.Root
      size={{ width }}
      onResize={({ width }) => setWidth(width)}
      className="relative h-screen min-w-24 max-w-[50vw]"
      asChild
    >
      <nav>
        <resizable.Handle
          // invert the calculations of the width resizing
+         ratio={{ width: -1, height: 0 }}
-         ratio={{ width: 1, height: 0 }}
          // place the handle on the left side
+         className="transition absolute z-10 left-0 top-0 h-full -translate-x-1/2 w-1.5 hover:bg-teal-700/30 data-[active]:bg-teal-700/50 overflow-auto"
-         className="transition absolute z-10 right-0 top-0 h-full translate-x-1/2 w-1.5 hover:bg-teal-700/30 data-[active]:bg-teal-700/50 overflow-auto"
          cursor="col-resize"
        />
        <ul>
          <li>...</li>
          <li>...</li>
          <li>...</li>
        </ul>
      </nav>
    </resizable.Root>
  )
}

3. Resize Direction & Centered elements

When working with elements that are centered, using a ratio of 1 or -1 will cause the handle to move at half the speed of the mouse. This happens because the handle is centered, and the resizing effect is spread across both sides of the element.

To fix this behavior, you should use ratio values of 2 or -2, effectively doubling the movement of the handle so it matches the mouse speed.

As a general rule:

use a negative ratio for top and left handles
use a positive ratio for bottom and right handles

The following example demonstrates how to apply the ratio for all possible handle positions:

function Centered() {
  const [size, setSize] = useState<Size>({
    width: '300px',
    height: '300px',
  })

  return (
    // The outer div centers the Root on the screen
    <div className="flex h-screen w-screen items-center justify-center">
      <resizable.Root className="relative" size={size} onResize={setSize}>
        {/* Top handle */}
        <resizable.Handle
          cursor="row-resize"
          ratio={{ width: 0, height: -2 }}
          className="absolute left-1/2 top-0 size-4 -translate-x-1/2 -translate-y-1/2 bg-slate-200 data-[active]:bg-red-500"
        />
        {/* Top-Right handle */}
        <resizable.Handle
          cursor="move"
          ratio={{ width: 2, height: -2 }}
          className="absolute right-0 top-0 size-4 -translate-y-1/2 translate-x-1/2 bg-slate-200 data-[active]:bg-red-500"
        />
        {/* Right handle */}
        <resizable.Handle
          cursor="col-resize"
          ratio={{ width: 2, height: 0 }}
          className="absolute right-0 top-1/2 size-4 -translate-y-1/2 translate-x-1/2 bg-slate-200 data-[active]:bg-red-500"
        />
        {/* Bottom-Right handle */}
        <resizable.Handle
          cursor="move"
          ratio={{ width: 2, height: 2 }}
          className="absolute bottom-0 right-0 size-4 translate-x-1/2 translate-y-1/2 bg-slate-200 data-[active]:bg-red-500"
        />
        {/* Bottom handle */}
        <resizable.Handle
          cursor="row-resize"
          ratio={{ width: 0, height: 2 }}
          className="absolute bottom-0 left-1/2 size-4 -translate-x-1/2 translate-y-1/2 bg-slate-200 data-[active]:bg-red-500"
        />
        {/* Bottom-Left handle */}
        <resizable.Handle
          cursor="move"
          ratio={{ width: -2, height: 2 }}
          className="absolute bottom-0 left-0 size-4 -translate-x-1/2 translate-y-1/2 bg-slate-200 data-[active]:bg-red-500"
        />
        {/* Left handle */}
        <resizable.Handle
          cursor="col-resize"
          ratio={{ width: -2, height: 0 }}
          className="absolute left-0 top-1/2 size-4 -translate-x-1/2 -translate-y-1/2 bg-slate-200 data-[active]:bg-red-500"
        />
        {/* Top-Left handle */}
        <resizable.Handle
          cursor="move"
          ratio={{ width: -2, height: -2 }}
          className="absolute left-0 top-0 size-4 -translate-x-1/2 -translate-y-1/2 bg-slate-200 data-[active]:bg-red-500"
        />
      </resizable.Root>
    </div>
  )
}

4. Usage with Tailwind

You might want to leverage Tailwind to define the initial size of your elements, particularly when adjusting sizes across breakpoints and media queries.

This can be done by omitting the width and/or height properties from the initial size object, allowing Tailwind classes to dictate the initial dimensions.

function Resizable() {
  // uncontrolled initial size
  const [size, setSize] = useState<Size>({})

  return (
    <resizable.Root
      /**
       * the default size is:
       * - mobile device: width: 100%; height: 100%
       * - tablet / desktop: width: 300px; height: 300px
       */
      className="relative h-full w-full md:h-[300px] md:w-[300px]"
      /**
       * Set the size when resize occurs
       */
      onResize={setSize}
      /**
       * The size is controlled by:
       * - the className initially
       * - the size state after a resize occurs
       */
      size={size}
    >
      ...
    </resizable.Root>
  )
}

5. Improving Performance

Resizing DOM elements can be performance-intensive because each size change triggers a browser reflow and repaint. To minimize this, you can use the resizable element as a mask, following these steps:

Set a positioning context (e.g. "relative") for the element you want to resize.
disable flex-shrink to prevent unexpected behaviors.
Position the Root and Handle(s) on top of the target element, matching its size.
Disable pointer events on the Root but re-enable them on the Handle(s) for interactivity.
Update the width of the target element using the onResizeEnd event.

function Sidebar() {
  const [resizableWidth, setResizableWidth] = useState<Size['width']>()
  const [sidebarWidth, setSidebarWidth] = useState<Size['width']>()

  return (
    <nav
      style={{ width: sidebarWidth }}
      // disable `flex-shrink` to prevent unexpected behaviors
      className="relative h-screen min-w-24 max-w-[50vw] shrink-0"
    >
      <ul>
        <li>...</li>
        <li>...</li>
        <li>...</li>
      </ul>

      <resizable.Root
        size={{ width: resizableWidth }}
        // position on top the sidebar
        // disable pointer events
        // add a semi-transparent background when resizing
        className="pointer-events-none absolute inset-0 data-[resizing]:bg-cyan-500/10"
        // Continuously update the Root width
        onResize={({ width }) => setResizableWidth(width)}
        // Update the sidebar width when resizing ends
        onResizeEnd={() => setSidebarWidth(resizableWidth)}
      >
        <resizable.Handle
          ratio={{ width: 1, height: 0 }}
          cursor="col-resize"
          // Position the handle on the right edge
          // enable pointer events
          className="pointer-events-auto absolute inset-y-0 left-full w-2 -translate-x-1/2 hover:bg-cyan-500/50 data-[active]:bg-cyan-500"
        />
      </resizable.Root>
    </nav>
  )
}

API Reference

👉 `resizable.Root`

The resizable element

Props

Prop	Type	Default
`size`	`Size`	-
`onResizeEnd?`	`(() => void)`	-
`onResize?`	`((size: MeasuredSize) => void)`	-
`locked?`	`boolean`	-
`children?`	`ReactNode \| ((props: Size & { isResizing: boolean; }) => ReactNode)`	-
`asChild?`	`boolean`	-

Data Attributes

Prop	Type	Default
`data-locked?`	`"true" \| undefined`	-
`data-resizing?`	`"true" \| undefined`	-
`data-resizable?`	`"true"`	-

👉 `resizable.Handle`

The Handles for resizing the Root element.

Props

Prop	Type	Default
`onResizeEnd?`	`(() => void)`	-
`onResize?`	`((size: MeasuredSize) => void)`	-
`ratio`	`Ratio`	-
`cursor?`	`Cursor`	-
`children?`	`ReactNode \| ((props: { isActive: boolean; }) => ReactNode)`	-
`asChild?`	`boolean`	-

Data Attributes

Prop	Type	Default
`data-locked?`	`"true" \| undefined`	-
`data-active?`	`"true" \| undefined`	-
`data-handle?`	`"true"`	-

@crustack/resizable

Quick Start

Define the resizable components

Create a resizable element with the `Root` component.

Add Resize Handles with the `Handle` component.

Examples

1. Left aligned Sidebar

2. Right aligned Sidebar

3. Resize Direction & Centered elements

4. Usage with Tailwind

5. Improving Performance

API Reference

👉 `resizable.Root`

Props

Data Attributes

👉 `resizable.Handle`

Props

Data Attributes

On this page