@yoyoo-ddr/react

React component for DDR — Draggable, Resizable, Rotatable. Built on top of @yoyoo-ddr/core.

Install

npm i @yoyoo-ddr/react --save

Requires react and react-dom ≥ 16.8.0 (peer dependencies). @yoyoo-ddr/core is included as a dependency.

Quick Start

Controlled Component (recommended)

import { useState } from 'react'
import DDR from '@yoyoo-ddr/react'
import type { TransformProps } from '@yoyoo-ddr/react'
import '@yoyoo-ddr/react/dist/style.css'

function App() {
  const [value, setValue] = useState<TransformProps>({
    x: 100, y: 100, width: 100, height: 100, rotation: 0,
  })

  return (
    <div style={{ width: '100%', height: '100%' }}>
      <DDR
        value={value}
        onChange={(_, t) => setValue(t)}
        parent={true}
        grid={[10, 10]}
        minWidth={20}
        minHeight={20}
      >
        <div style={{ width: '100%', height: '100%', background: 'red' }} />
      </DDR>
    </div>
  )
}

With Ref (imperative handle)

import { useRef, useState } from 'react'
import DDR, { type DDRHandle } from '@yoyoo-ddr/react'
import type { TransformProps } from '@yoyoo-ddr/react'

function App() {
  const ddrRef = useRef<DDRHandle>(null)
  const [value, setValue] = useState<TransformProps>({
    x: 0, y: 0, width: 100, height: 100, rotation: 0,
  })

  const reset = () => {
    // Read current value
    console.log(ddrRef.current?.getValue())
    // Dynamically update config
    ddrRef.current?.updateConfig({ minWidth: 50 })
  }

  return (
    <div style={{ width: '100%', height: '100%' }}>
      <DDR ref={ddrRef} value={value} onChange={(_, t) => setValue(t)}>
        <div style={{ width: '100%', height: '100%', background: 'blue' }}>
          <button onClick={reset}>Reset</button>
        </div>
      </DDR>
    </div>
  )
}

DDRHandle (Ref API)

| Method | Signature | Description | |--------|-----------|-------------| | getValue | () => TransformProps | Return a copy of the current transform | | updateConfig | (partial: Partial<DDRCoreConfig>) => void | Update config at runtime |

Props

All props are optional.

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | TransformProps | { x:0, y:0, width:100, height:100, rotation:0 } | Controlled value | | onChange | DDREventCallback | — | Fires on every interaction tick | | active | boolean | true | Whether interaction is enabled | | draggable | boolean | true | Enable drag | | resizable | boolean | true | Enable resize | | rotatable | boolean | true | Enable rotation | | resizeHandler | HanlderType[] | ['tl','tm','tr','r','br','bm','bl','l'] | Visible resize handles | | handlerSize | number | 11 | Resize handle size in px | | acceptRatio | boolean | false | Lock aspect ratio (hold Shift to toggle) | | minWidth | number | 1 | Minimum width | | minHeight | number | 1 | Minimum height | | maxWidth | number | 1000000 | Maximum width | | maxHeight | number | 1000000 | Maximum height | | parent | boolean | false | Constrain to parent bounds | | grid | [number, number] | [1, 1] | Grid snap [x, y] | | axis | 'x' 'y' 'xy' | 'xy' | Restrict drag axis | | zoom | number | 1 | Parent scale factor | | useCSSTransform | boolean | false | Use CSS transform for positioning | | transformOrigin | [number, number] | [0, 0] | Parent transform-origin in px | | stop | boolean | true | Stop event propagation | | prevent | boolean | true | Prevent default events | | beforeActive | () => boolean | () => false | Guard before interaction | | className | string | — | CSS class for the inner content div | | style | CSSProperties | — | Inline styles for the inner content div |

Event Callbacks

Each callback follows the signature:

type DDREventCallback = (event: MouseEvent | TouchEvent, transform: TransformProps) => void

| Prop | Description | |------|-------------| | onChange | Fires on every interaction tick | | onDragStart | Drag started | | onDrag | Dragging | | onDragEnd | Drag ended | | onResizeStart | Resize started | | onResize | Resizing | | onResizeEnd | Resize ended | | onRotateStart | Rotate started | | onRotate | Rotating | | onRotateEnd | Rotate ended |

Re-exports from Core

For convenience, @yoyoo-ddr/react re-exports core types and the DDRCore class:

import type { TransformProps, DDRCoreConfig, HanlderType } from '@yoyoo-ddr/react'
import { DDRCore } from '@yoyoo-ddr/react'
import type { DDRReactProps, DDREventCallback } from '@yoyoo-ddr/react'

CSS State Classes

| Class | Description | |-------|-------------| | yoyoo-ddr | Wrapper (always present) | | active | Component is active | | ddr-ready-drag | Ready to drag | | ddr-dragging | Dragging | | ddr-ready-resize | Ready to resize | | ddr-resizing | Resizing | | ddr-ready-rotate | Ready to rotate | | ddr-rotating | Rotating |

License

MIT