@docusaurus/mdx-loader

React Paint

An open-source canvas-based library for React used for image annotation or as a digital whiteboard

Features

Quick start

npm i @yorab/react-paint

Note : react-paint needs react and react-dom packages to work properly

Usage

Basic usage

import { Canvas, Editor, useReactPaint } from '@yorab/react-paint'

const BasicUsage = () => {
  const { editorProps, canvasProps } = useReactPaint()

  return (
    <Editor editorProps={editorProps}>
      <Canvas canvasProps={canvasProps} />
    </Editor>
  )
}

Advanced usage

import { useEffect, useState } from 'react'
import { Canvas, Editor, useReactPaint, type DrawableShape, type StateData } from '@yorab/react-paint'

const SHAPES_INIT = [
  {
    type: 'rect',
    x: 300,
    y: 300,
    width: 100,
    height: 200,
    rotation: 0,
    style: {
      fillColor: '#6a4e01',
      strokeColor: 'transparent',
      opacity: 100,
      lineWidth: 1,
      lineDash: 0,
      lineArrow: 0,
      pointsCount: 3,
      fontFamily: 'serif'
    }
  }
]

const AdvancedUsage = () => {
  const [shapes, setShapes] = useState<DrawableShape[] | undefined>(SHAPES_INIT) // keep shapes state for internal use

  const { editorProps, canvasProps, registerEvent, unregisterEvent } = useReactPaint({
    width: 1920,
    height: 1080,
    shapes,
    options: {
      canGrow: true,
      canShrink: true,
      brushAlgo: 'quadratic',
      clearCallback: 'defaultShapes'
    }
  })

  const editorOptions = {
    fontColor: '#2c1e69',
    fontHoverColor: '#0d0931'
  }

  const canvasOptions = {
    canvasBackgroundColor: '#ffffff'
  }

  useEffect(() => {
    const onDataChanged = (data: StateData, source: 'user' | 'remote') => {
      setShapes(data.shapes)
    }
    registerEvent('dataChanged', onDataChanged)
    
    return () => {
      unregisterEvent('dataChanged', onDataChanged)
    }
  }, [registerEvent, unregisterEvent])

  return (
    <Editor editorProps={editorProps} options={editorOptions}>
      <Canvas canvasProps={canvasProps} options={canvasOptions} />
    </Editor>
  )
}

Other usages

you will find other usages in stories

API

useReactPaint

Parameters

Parameter	Type	Description	Default value
width	number	Optional. Canvas width in px	1000
height	number	Optional. Canvas height in px	600
shapes	DrawableShape[]	Optional. Array of shapes used to init the canvas	undefined
mode	editor|viewer	Optional. editor lets you interact with the canvas and editor. viewer hides the editor and makes the canvas read-only	editor
disabled	boolean	Optional. Global parameter used to prevent interaction with every element in the editor or canvas	false
options	OptionalOptions	Optional. Set of options to customize available features	See OptionalOptions

Returns

Parameter	Type	Description
canvasProps	object	Set of properties to forward to Canvas component
editorProps	object	Set of properties to forward to Editor component
registerEvent	(event: "dataChanged", listener: (data: StateData, source: 'user' | 'remote') => void) => void	registerEvent is used to register a listener for special events triggered by react-paint. The only currently available event is dataChanged. source indicates the origin of the state update
unregisterEvent	(event: "dataChanged", listener?: ((data: StateData, source: 'user' | 'remote') => void) | undefined) => void	unregisterEvent is used to unregister a listener previously registered. Omitting listener will result in unregistering every listeners for the the given event
resetCanvas	(shapes: DrawableShape[], clearHistory?: boolean) => Promise<void>	reset canvas with the given shapes. use [] or undefined to clear the canvas. Set false to clearHistory to prevent history stack to be cleared
getCurrentImage	() => string | undefined	Returns a data URL containing the content of the current canvas as a PNG image, or undefined if an error occured
getCurrentData	() => StateData	Returns the current state of the canvas

OptionalOptions

Parameter	Type	Description	Default value
layersManipulation	boolean	Optional. Show panel to manipulate layers	true
grid	number	Optional. Size in px for grid cells. Set to 0 to hide grid	0
canGrow	boolean	Optional. Allow canvas to upscale and grow to fit container	false
canShrink	boolean	Optional. Allow canvas to downscale and shrink to fit container	true
withExport	boolean	Optional. Show button to manually export to PNG	true
withLoadAndSave	boolean	Optional.Show button to manually save or load data	true
withUploadPicture	boolean	Optional. Show button to add picture shape stored in base64	true
withUrlPicture	boolean	Optional.Show button to add picture shape with only the url stored. Need connectivity to be displayed	false
withFrameSelection	boolean	Optional.Enable frame selection. Currently, does not support multi shapes selection	false
withSkeleton	boolean	Optional. Display skeleton when hovering shape	false
clearCallback	'empty' | 'defaultShapes' | (() => DrawableShape[])	Optional. Set clear button behavior. empty clear all shapes, defaultShapes uses shapes given in props. It is also possible to set a function returning an array of shapes	empty
brushAlgo	'simple' | 'quadratic'	Optional. Choose which algorithm to display brush shape. simple displays path as is, quadratic uses quadratic bézier curves	simple
isBrushShapeDoneOnMouseUp	boolean	Optional. Choose whether drawing brush shape after releasing mouse should create a new shape or not	true
canvasSelectionPadding	boolean	Optional. Padding between shape and selection frame	0
availableTools	CustomToolInput[]	Optional. List of available tools. See CustomTool for more details	``

Canvas

Parameters

Parameter	Type	Description	Default value
canvasProps	object	Required. Set of properties coming from useReactPaint
className	string	Optional. Classname for canvas parent node	undefined
style	CSSProperties	Optional. css properties to inject to canvas parent node	undefined
options	{canvasBackgroundColor?: string; canvasSelectionColor?: string; canvasSelectionWidth?: number}	Optional. Set of properties to use to customize canvas style	{canvasBackgroundColor: 'white'; canvasSelectionColor: 'blue'; canvasSelectionWidth: 2}

Editor

Parameters

Parameter	Type	Description	Default value
editorProps	object	Required. Set of properties coming from useReactPaint
children	ReactNode	Required. Need Canvas component to work properly
className	string	Optional. Classname for canvas parent node	undefined
style	CSSProperties	Optional. css properties to inject to canvas parent node	undefined
options	{ toolbarBackgroundColor?: string; dividerColor?: string; fontRadius?: number; fontDisabledColor?: string; fontDisabledBackgroundColor?: string; fontColor?: string; fontBackgroundColor?: string; fontSelectedColor?: string; fontSelectedBackgroundColor?: string; fontHoverColor?: string; fontHoverBackgroundColor?: string; }	Optional. Set of properties to use to customize editor style	{ toolbarBackgroundColor: 'white', dividerColor: '#36418129', fontRadius: 8, fontDisabledColor: '#3641812b', fontDisabledBackgroundColor: 'transparent', fontColor: '#364181', fontBackgroundColor: 'transparent', fontSelectedColor: 'white', fontSelectedBackgroundColor: '#364181', fontHoverColor: '#364181', fontHoverBackgroundColor: '#afd8d8'}

Types

DrawableShape

StateData

CustomTool

 type CustomTool = {
  id: string
  icon: string
  label: string
} & (
  | {
      type: 'brush'
      settings: ToolsSettingsType<'brush'>
    }
  | {
      type: 'circle'
      settings: ToolsSettingsType<'circle'>
    }
  | {
      type: 'ellipse'
      settings: ToolsSettingsType<'ellipse'>
    }
  | {
      type: 'rect'
      settings: ToolsSettingsType<'rect'>
    }
  | {
      type: 'square'
      settings: ToolsSettingsType<'square'>
    }
  | {
      type: 'line'
      settings: ToolsSettingsType<'line'>
    }
  | {
      type: 'polygon'
      settings: ToolsSettingsType<'polygon'>
    }
  | {
      type: 'curve'
      settings: ToolsSettingsType<'curve'>
    }
  | {
      type: 'text'
      settings: ToolsSettingsType<'text'>
    }
  | {
      type: 'picture'
      settings: ToolsSettingsType<'picture'>
    }
)

type SettingsOpacity = {
  opacity: {
    min: number
    max: number
    step: number
    default: number
    hidden?: boolean
  }
}

type SettingsStrokeColor = {
  strokeColor: {
    values: string[]
    default: string
    hidden?: boolean
  }
}

type SettingsFillColor = {
  fillColor: {
    values: string[]
    default: string
    hidden?: boolean
  }
}

type SettingsLineWidth = {
  lineWidth: {
    min: number
    max: number
    step: number
    default: number
    hidden?: boolean
  }
}

type SettingsLineDash = {
  lineDash: {
    values: number[]
    default: number
    hidden?: boolean
  }
}

type SettingsLineArrow = {
  lineArrow: {
    values: number[]
    default: number
    hidden?: boolean
  }
}

type SettingsFont = {
  fontFamily: {
    values: string[]
    default: string
    hidden?: boolean
  }
  fontBold: {
    values: boolean[]
    default: boolean
    hidden?: boolean
  }
  fontItalic: {
    values: boolean[]
    default: boolean
    hidden?: boolean
  }
}

type SettingsPointsCount = {
  pointsCount: {
    min: number
    max: number
    step: number
    default: number
    hidden?: boolean
  }
}

type ToolsRectSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash

type ToolsSquareSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash

type ToolsCircleSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash

type ToolsEllipseSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash

type ToolsTextSettings = SettingsOpacity & SettingsStrokeColor & SettingsFont

type ToolsLineSettings = SettingsOpacity & SettingsStrokeColor & SettingsLineWidth & SettingsLineDash & SettingsLineArrow

type ToolsBrushSettings = SettingsOpacity & SettingsStrokeColor & SettingsLineWidth & SettingsLineDash

type ToolsPolygonSettings = SettingsOpacity &
  SettingsStrokeColor &
  SettingsFillColor &
  SettingsLineWidth &
  SettingsLineDash &
  SettingsPointsCount

type ToolsCurveSettings = SettingsOpacity &
  SettingsStrokeColor &
  SettingsFillColor &
  SettingsLineWidth &
  SettingsLineDash &
  SettingsPointsCount

type ToolsTriangleSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash

type ToolsPictureSettings = SettingsOpacity

type ToolsSettingsType<T extends ShapeType> = T extends 'rect'
  ? ToolsRectSettings
  : T extends 'square'
    ? ToolsSquareSettings
    : T extends 'circle'
      ? ToolsCircleSettings
      : T extends 'ellipse'
        ? ToolsEllipseSettings
        : T extends 'text'
          ? ToolsTextSettings
          : T extends 'line'
            ? ToolsLineSettings
            : T extends 'brush'
              ? ToolsBrushSettings
              : T extends 'polygon'
                ? ToolsPolygonSettings
                : T extends 'curve'
                  ? ToolsCurveSettings
                  : T extends 'triangle'
                    ? ToolsTriangleSettings
                    : T extends 'picture'
                      ? ToolsPictureSettings
                      : never

Changelog

https://github.com/YoRab/react-paint-editor/blob/main/Changelog.md

License

MIT

Contributing