> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ResizeHandle
> Resize a panel with pointer dragging or keyboard controls.
export const StoryEmbed = ({storyId, title, height = 120}) => <>
Open in Storybook
;
`ResizeHandle` manages a numeric size and exposes a focusable separator. The application applies that size to the panel; the handle does not resize another element automatically.
## Usage
Use `edge` for a panel boundary, or `axis="y"` for inline height resizing and `axis="x"` for inline width resizing. Give the handle a specific accessible name and use `aria-controls` to identify the panel.
```tsx theme={null}
import { useId, useState } from 'react';
import { ResizeHandle } from 'twenty-ui/primitives/layout';
import { Card } from 'twenty-ui/primitives/surfaces';
import { Text } from 'twenty-ui/primitives/typography';
export const ResizableNotes = () => {
const panelId = useId();
const [height, setHeight] = useState(150);
return (
Record notes
Follow up with Morgan about the proposal. Share the revised timeline
before Friday.
);
};
```
The handle owns its value. `onValueChange` copies the latest size to the panel layout without controlling the handle. `defaultValue` only sets the initial size.
## Controlled state
```tsx theme={null}
import { useId, useState } from 'react';
import { ResizeHandle } from 'twenty-ui/primitives/layout';
import { Card } from 'twenty-ui/primitives/surfaces';
import { Text } from 'twenty-ui/primitives/typography';
export const ResizableNotes = () => {
const panelId = useId();
const [height, setHeight] = useState(150);
return (
Record notes
Follow up with Morgan about the proposal. Share the revised timeline
before Friday.
);
};
```
The application owns the value and can update it from other controls. Reflect live changes in `value`; use `onValueCommitted` to save the final size. Keep `value` and `defaultValue` separate and retain the same ownership mode throughout the component's lifetime.
## Panel edges and gaps
`edge="left"`, `"right"`, `"top"` or `"bottom"` determines both the axis and the physical increasing direction. Leftward movement grows a left edge, upward movement grows a top edge, and the opposite applies to right and bottom edges. This behavior stays the same in right-to-left content. Use either `edge` or `axis` and `direction`.
With `edge`, placement defaults to `"edge"`. Put the handle inside a panel with `position: 'relative'` to position it along that boundary. `placement="inline"` keeps it in normal flow. Use `placement="gap"` between sibling panels and set its width or height through `style` when the layout needs a gap. Gap handles have no visible grip by default.
```tsx theme={null}
import { useId, useState } from 'react';
import { ResizeHandle } from 'twenty-ui/primitives/layout';
import { Card } from 'twenty-ui/primitives/surfaces';
import { Text } from 'twenty-ui/primitives/typography';
export const ResizableDetails = ({
saveWidth,
}: {
saveWidth: (value: number) => void;
}) => {
const detailsId = useId();
const [width, setWidth] = useState(380);
return (
Activity
Details
);
};
```
The application owns the layout, saved size, collapse state and focus destination when collapsing removes the handle. Use `onActivate` for an optional collapse action.
## Keyboard and bounds
For `axis="y"`, Down increases the size and Up decreases it. For `axis="x"`, Right increases and Left decreases in left-to-right content; the directions reverse under [DirectionProvider](/ui/primitives/layout/direction-provider) with `direction="rtl"`.
Arrow keys use `step`, which defaults to `10`. Home moves to `min`, and End moves to `max`. Keys pressed with Alt, Control or Meta are ignored. Pointer dragging uses the pixel movement and is not snapped to `step`. Both interactions stay within the bounds. Pointer presses do not move focus; keyboard users reach the handle with Tab. `disabled` prevents resizing and removes the handle from the tab order.
The separator orientation describes the dividing edge: horizontal for height resizing and vertical for width resizing.
## Physical directions and zoom
Set `direction="normal"` or `direction="reverse"` when increasing size must follow a fixed physical direction, regardless of text direction. Normal increases with rightward or downward movement. Reverse increases with leftward or upward movement. Omit `direction` to retain the text-direction behavior described above.
`scale` accepts a positive zoom factor or a function returning one. The handle samples it at pointer down and divides pointer movement by that value. Keyboard steps remain unchanged.
## Gesture lifecycle
`onValueChange` reports live values. `onValueCommitted` reports the final value after a successful pointer drag or an effective keyboard change. Home, End and arrow keys commit immediately when they change the size.
`onResizeStart` receives the first bounded candidate after the pointer passes `dragThreshold`. The threshold defaults to `5` with `edge` and `0` otherwise, measured in physical pixels. `onResizeEnd` receives `{ cancelled, value }` for a started drag. Escape, pointer cancellation, lost pointer capture and unmounting cancel the gesture without committing; disabling the handle cancels it on its next pointer event. Cancellation calls `onValueChange` with the starting value, clamped to the current bounds. `onResizeEnd` receives that restored value.
Supply `onActivate` to handle a click without dragging, Enter or Space. Crossing the threshold prevents the following pointer click from activating, even when the pointer returns to its starting position.
Native handlers run before the handle's interaction. Calling `preventDefault()` in `onPointerDown` or `onKeyDown` skips that interaction. Preventing `onPointerMove` skips only that update and leaves the gesture active. Preventing `onPointerUp` cancels the drag, restores the starting bounded value and skips `onValueCommitted`. Pointer cancellation and lost capture still end the gesture.
## Custom handle
`ref`, native attributes, `className`, `style` and native event handlers target the separator root, a `div` by default. The ref does not target the resized panel or the visible grip.
`children` replaces the visible grip, and `children={null}` hides it; it does not replace the separator behavior. `render` can replace the root element, and the ref then targets that replacement. Custom wrappers must [forward the supplied props and ref](/ui/primitives/overview#custom-components) so focus, pointer capture, keyboard handlers, and accessibility attributes reach the same element.
## Props
Pointer movement axis without `edge`: `y` for height or `x` for width.
Initial size when the handle owns its state.
Physical increasing direction. Omit to follow the horizontal text direction; use `normal` or `reverse` for a fixed physical edge.
Disables resizing and removes the handle from the tab order.
Physical pointer distance required before resizing starts. Movement below the threshold remains a click. Defaults to 5 with `edge` and 0 otherwise.
Physical panel edge. Determines the movement axis and increasing direction, independently of text direction.
Maximum allowed size.
Minimum allowed size.
Called for a click without dragging, Enter, or Space.
Called after a started drag ends, with its final value and whether it was cancelled. Cancellation restores the starting value within the current bounds.
Called once with the first bounded drag value after the threshold is crossed.
Called with the bounded size during pointer or keyboard interaction and with the restored value on cancellation.
Called with the final size after a successful drag or an effective keyboard size change. Cancellation does not commit.
Layout mode: `inline` stays in normal flow, `edge` positions the handle on the panel edge, and `gap` sits between panels. Defaults to `edge` when `edge` is set and `inline` otherwise.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
Pointer scale or resolver sampled at pointer down. Movement is divided by this positive scale; keyboard steps are unchanged.
Keyboard arrow increment. Pointer movement uses the pixel delta.
Current controlled size. Update it in `onValueChange` and apply it to the element being resized.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.