# DragHandle

```ts
import {
  DragHandle,
  ManipulationFrame,
  Rectangle,
  useManipulation,
  useSignal,
} from "@pibbl/core";
```

`DragHandle` starts a move interaction for its controller. Its children provide the hit areas through normal Pibbl event targeting. It adds
no target of its own: empty space, gaps between children, and descendants with
`pointerEvents="none"` do not start dragging. Shapes retain their transforms,
clips, fill and stroke hit rules. Place it inside the `ManipulationFrame` attached
to the same controller.

```tsx
const box = useSignal({ left: 40, top: 32, width: 180, height: 100 });
const manipulation = useManipulation({ box, move: {} });

<ManipulationFrame {...manipulation.frameProps}>
  <DragHandle controller={manipulation} style={{ readout: true }}>
    <Rectangle
      keyboardFocusable
      style={{ width: 180, height: 100, fill: "#2563eb", cursor: "grab" }}
    />
  </DragHandle>
</ManipulationFrame>;
```

Related types: [PibblDragHandleProps](/reference/types/events/#pibbldraghandleprops), [PibblDragHandleStyle](/reference/types/events/#pibbldraghandlestyle), [PibblManipulationController](/reference/types/events/#pibblmanipulationcontroller).

Position readouts display the frame’s applied `left` and `top`, default to active-only, and accept the same `style.readout` states, gap, and canvas containment as resize readouts. `formatReadout={({ left, top }) => ...}` can display custom document units. Put `keyboardFocusable` and cursor styling on the actual child target. Child event cancellation can reject a drag before it reaches the handle.

The position readout sits outside the top edge with a default gap of 40 CSS
pixels, leaving room for the standard rotation handle and guide arc. Set
`style={{ readout: { gap: 48 } }}` to adjust that distance. The gap follows the
rotated edge; canvas containment takes priority near the canvas boundary.
Readouts do not currently support independent horizontal/vertical offsets.

## API details from source

<span id="api-DragHandle"></span>

Draws an interactive handle that starts translation of its manipulation target.

```ts
DragHandle: PibblPrimitiveComponent<PibblDragHandleProps, PrimitiveInput<PibblDragHandleProps, PibblDragHandleStyle>>
```

Related API: [DragHandle](/reference/components/drag-handle/), [PibblPrimitiveComponent](/reference/types/elements-components/#pibblprimitivecomponent), [PibblDragHandleProps](/reference/types/events/#pibbldraghandleprops), [PrimitiveInput](/reference/types/styles/#primitiveinput), [PibblDragHandleStyle](/reference/types/events/#pibbldraghandlestyle).

### Parameters

- **`props`** — Authored component inputs, supplied through JSX or createElement. See the linked
props and style types.

### Throws

When called directly; Pibbl mounts this component through JSX or createElement.

### See also

[PibblDragHandleProps](/reference/types/events/#pibbldraghandleprops)

[PibblDragHandleStyle](/reference/types/events/#pibbldraghandlestyle)

[View source — packages/core/src/lib/manipulation/handles.ts:101](/source/packages/core/src/lib/manipulation/handles-ts/#L101)

## Implementation guidance for agents

Read the [Input, focus, and native HTML companion](/agents/topics/input/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Own a manipulation controller](/minimal-examples/manipulation/controller/): Compose a drag surface and one resize handle, inspect gesture state, and cancel explicitly. [Plain source](/minimal/manipulation/controller.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.