react-native-sketch-canvas-enhanced
Version:
Enhanced react-native-sketch-canvas with shape drawing tools and advanced text annotations. Draw, sketch, and annotate on both iOS and Android devices.
664 lines (573 loc) • 59.1 kB
Markdown
# react-native-sketch-canvas-enhanced
_Enhanced version of react-native-sketch-canvas with shape drawing tools and advanced text annotations._
---
A React Native component for drawing, creating shapes, and adding text annotations by touching on both iOS and Android.
## Features
- Support iOS and Android
- Stroke thickness and color are changeable while drawing
- Draw basic shapes: lines, rectangles, circles, and arrows
- Optimized for outlining and annotating images
- Enhanced text annotations with formatting options
- Can undo strokes and shapes one by one
- Can serialize path and shape data to JSON for syncing between devices
- Save drawing to a non-transparent image (png or jpg) or a transparent image (png only)
- Use vector concept so sketches won't be cropped in different sizes of canvas
- Support translucent colors and eraser
- Support drawing on an image
- High performance drawing
- Can draw multiple canvases in the same screen
- Can draw multiple multiline text on canvas with enhanced formatting
## Changelog
### v1.8.6
- **Fixed text positioning**: Text elements now appear at the exact coordinates specified
- **Improved anchor point handling**: Text anchoring now works correctly for all text elements
- **Enhanced text selection visuals**: Added visual indicators for selected text with drag handles
- **Better text measurement**: More accurate text bounds calculation for better hit detection
### v1.8.5
- **Enhanced text functionality**: Text elements can now be dragged and moved around the canvas after placement
- **Improved text selection**: Better hit detection for text elements with more accurate bounds calculation
- **Fixed text conflicts**: Resolved issues with text annotations conflicting with shapes and drawing
- **Performance improvements**: Optimized text rendering and interaction
### v1.8.0
- **TypeScript support for consumers**: All types are now exported and declaration files are generated, so you get full type safety and auto-complete when importing the library.
- **Bugfix**: Rectangle drawing now produces a fully connected rectangle.
- **Feature**: Text annotations can now be placed anywhere by tapping the canvas.
- **Type safety**: Fixed all TypeScript errors and improved type exports for better DX.
### v1.6.0
- Added text selection and movement functionality
- Implemented text annotation features on Android
- Fixed rectangle drawing to properly render clean rectangles
- Added ability to add text at any position on the canvas
- Improved text handling across both iOS and Android
### v1.5.0
- Fixed rectangle drawing to ensure proper shape rendering
- Removed fill functionality as the component is now optimized for outlining images
- Improved performance for shape drawing
## New Features in Enhanced Version
### Shape Drawing Tools
- Draw lines, rectangles, circles, and arrows
- Optimized for outlining and annotating images
- Customize stroke color and width for shapes
- Undo shapes individually
### Advanced Text Annotations
- Add text anywhere on the canvas
- Edit text content with a built-in editor
- Customize text with various formatting options:
- Font size, color, and style (bold, italic)
- Text alignment (left, center, right)
- Background color
- Border options (width, color, radius)
- Text decoration (underline, line-through)
- Rotation
- Tap on text to edit it
## Installation
---
Install from `npm` or `yarn` (supports RN >= 0.60)
```bash
npm install react-native-sketch-canvas-enhanced
```
or
```bash
yarn add react-native-sketch-canvas-enhanced
```
## Usage
---
### ● Basic Usage
```javascript
import React, {Component} from 'react';
import {StyleSheet, View} from 'react-native';
import {SketchCanvas} from 'react-native-sketch-canvas-enhanced';
export default class Example extends Component {
render() {
return (
<View style={styles.container}>
<View style={{flex: 1, flexDirection: 'row'}}>
<SketchCanvas
style={{flex: 1}}
strokeColor={'red'}
strokeWidth={7}
// Use 'draw' mode for freehand drawing
drawMode={'draw'}
/>
</View>
</View>
);
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#F5FCFF',
},
});
```
### ● Using Shape Drawing Tools
```javascript
import React, {Component} from 'react';
import {StyleSheet, View, TouchableOpacity, Text} from 'react-native';
import {SketchCanvas} from 'react-native-sketch-canvas-enhanced';
export default class ShapeExample extends Component {
constructor(props) {
super(props);
this.state = {
drawMode: 'draw',
shapeFilled: false,
};
}
render() {
return (
<View style={styles.container}>
{/* Drawing tools */}
<View style={styles.toolsContainer}>
<TouchableOpacity
style={[
styles.tool,
this.state.drawMode === 'draw' ? styles.selected : null,
]}
onPress={() => this.setState({drawMode: 'draw'})}>
<Text>Draw</Text>
</TouchableOpacity>
<TouchableOpacity
style={[
styles.tool,
this.state.drawMode === 'line' ? styles.selected : null,
]}
onPress={() => this.setState({drawMode: 'line'})}>
<Text>Line</Text>
</TouchableOpacity>
<TouchableOpacity
style={[
styles.tool,
this.state.drawMode === 'rectangle' ? styles.selected : null,
]}
onPress={() => this.setState({drawMode: 'rectangle'})}>
<Text>Rectangle</Text>
</TouchableOpacity>
<TouchableOpacity
style={[
styles.tool,
this.state.drawMode === 'circle' ? styles.selected : null,
]}
onPress={() => this.setState({drawMode: 'circle'})}>
<Text>Circle</Text>
</TouchableOpacity>
<TouchableOpacity
style={[
styles.tool,
this.state.drawMode === 'arrow' ? styles.selected : null,
]}
onPress={() => this.setState({drawMode: 'arrow'})}>
<Text>Arrow</Text>
</TouchableOpacity>
{/* Note: Fill functionality has been removed as it's optimized for outlining */}
</View>
{/* Canvas */}
<View style={{flex: 1}}>
<SketchCanvas
ref={ref => (this.canvas = ref)}
style={{flex: 1}}
strokeColor={'#000000'}
strokeWidth={4}
drawMode={this.state.drawMode}
// Note: shapeFilled prop is no longer used as fill functionality has been removed
onShapeStart={(x, y) => console.log('Shape started at', x, y)}
onShapeChanged={shape => console.log('Shape changed', shape)}
onShapeEnd={shape => console.log('Shape completed', shape)}
/>
</View>
</View>
);
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#F5FCFF',
},
toolsContainer: {
flexDirection: 'row',
padding: 10,
justifyContent: 'space-around',
},
tool: {
padding: 10,
borderRadius: 5,
backgroundColor: '#DDDDDD',
},
selected: {
backgroundColor: '#AAAAFF',
},
});
```
### ● Using Text Annotations
```javascript
import React, {Component} from 'react';
import {StyleSheet, View, TouchableOpacity, Text, Alert} from 'react-native';
import {SketchCanvas} from 'react-native-sketch-canvas-enhanced';
export default class TextAnnotationExample extends Component {
constructor(props) {
super(props);
this.state = {
text: [
{
id: 1,
text: 'Tap to edit me!\nDrag to move me!',
fontSize: 20,
fontColor: '#000000',
position: {x: 150, y: 200},
coordinate: 'Absolute',
alignment: 'Center',
fontWeight: 'bold',
backgroundColor: 'rgba(255, 255, 255, 0.7)',
padding: 10,
borderWidth: 1,
borderColor: '#000000',
borderRadius: 5,
},
],
pendingTextMode: false,
};
}
render() {
return (
<View style={styles.container}>
<View style={styles.toolsContainer}>
<TouchableOpacity
style={styles.tool}
onPress={() => {
// Enable pending text mode - next tap on canvas will add text
this.setState({ pendingTextMode: true });
Alert.alert('Tap anywhere on the canvas to add text');
}}>
<Text>Add Text</Text>
</TouchableOpacity>
</View>
<View style={{flex: 1}}>
<SketchCanvas
ref={ref => (this.canvas = ref)}
style={{flex: 1}}
text={this.state.text}
// Enable pending text mode to add text at tap location
pendingTextMode={this.state.pendingTextMode}
// Handle text placement
onTextPlaced={position => {
// Add new text at the tapped position
const newText = {
id: Date.now(),
text: 'New Text',
fontSize: 20,
fontColor: '#000000',
position: position,
coordinate: 'Absolute',
alignment: 'Left',
editable: true,
};
this.setState({
text: [...this.state.text, newText],
pendingTextMode: false // Exit pending text mode
});
}}
onTextTapped={textId => {
console.log('Text tapped', textId);
// Text will be automatically selected for dragging
}}
onTextEditingComplete={text => {
// Update the text in state
const updatedTexts = this.state.text.map(t =>
t.id === text.id ? text : t,
);
this.setState({text: updatedTexts});
}}
/>
</View>
</View>
);
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#F5FCFF',
},
toolsContainer: {
flexDirection: 'row',
padding: 10,
justifyContent: 'center',
},
tool: {
padding: 10,
borderRadius: 5,
backgroundColor: '#DDDDDD',
},
});
```
#### Properties
---
| Prop | Type | Description |
| :---------------------- | :--------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| style | `object` | Styles to be applied on canvas component |
| strokeColor | `string` | Set the color of stroke, which can be #RRGGBB or #RRGGBBAA. If strokeColor is set to #00000000, it will automatically become an eraser. <br/>NOTE: Once an eraser path is sent to Android, Android View will disable hardware acceleration automatically. It might reduce the canvas performance afterward. |
| strokeWidth | `number` | The thickness of stroke |
| drawMode | `string` | Drawing mode: 'draw' for freehand drawing, or a shape type ('line', 'rectangle', 'circle', 'arrow'). Default is 'draw'. |
| shapeFilled | `boolean` | **Deprecated**: Fill functionality has been removed as the component is optimized for outlining images. This prop has no effect. |
| shapes | `array` | Array of shape objects to render on the canvas |
| onStrokeStart | `function` | An optional function which accepts 2 arguments `x` and `y`. Called when user's finger touches the canvas (starts to draw) |
| onStrokeChanged | `function` | An optional function which accepts 2 arguments `x` and `y`. Called when user's finger moves |
| onStrokeEnd | `function` | An optional function called when user's finger leaves the canvas (end drawing) |
| onShapeStart | `function` | An optional function which accepts 2 arguments `x` and `y`. Called when user starts drawing a shape |
| onShapeChanged | `function` | An optional function which accepts 1 argument `shape`. Called when user is drawing a shape |
| onShapeEnd | `function` | An optional function which accepts 1 argument `shape`. Called when user completes drawing a shape |
| onTextTapped | `function` | An optional function which accepts 1 argument `textId`. Called when user taps on a text element. The text will be automatically selected for dragging |
| onTextEditingComplete | `function` | An optional function which accepts 1 argument `text`. Called when text editing is completed |
| pendingTextMode | `boolean` | When true, the next tap on the canvas will add a text element at that position. Default is false |
| onTextPlaced | `function` | An optional function which accepts 1 argument `position` (an object with x and y coordinates). Called when a text is placed on the canvas in pendingTextMode |
| onSketchSaved | `function` | An optional function which accepts 2 arguments `success` and `path`. If `success` is true, image is saved successfully and the saved image path might be in second argument. In Android, image path will always be returned. In iOS, image is saved to camera roll or file system, path will be set to null or image location respectively. |
| onPathsChange | `function` | An optional function which accepts 1 argument `pathsCount`, which indicates the number of paths. Useful for UI controls. |
| onShapesChange | `function` | An optional function which accepts 1 argument `shapesCount`, which indicates the number of shapes. Useful for UI controls. |
| user | `string` | An identifier to identify who draws the path or shape. Useful when undo between two users |
| touchEnabled | `bool` | If false, disable touching. Default is true. |
| text | `array` | Array of text objects to render on the canvas. Each text object can include enhanced formatting options (see [Text Properties](#text-properties)) |
| localSourceImage | `object` | Require an object (see [below](#objects)) which consists of `filename`, `directory`(optional) and `mode`(optional). If set, the image will be loaded and display as a background in canvas. |
| permissionDialogTitle | `string` | Android Only: Provide a Dialog Title for the Image Saving PermissionDialog. Defaults to empty string if not set |
| permissionDialogMessage | `string` | Android Only: Provide a Dialog Message for the Image Saving PermissionDialog. Defaults to empty string if not set |
#### Methods
---
| Method | Description |
| :---------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clear() | Clear all the paths, shapes, and reset the canvas |
| undo() | Delete the latest shape or path. Shapes are undone first, then paths. Can undo multiple times. |
| addPath(path) | Add a path (see [below](#objects)) to canvas. |
| deletePath(id) | Delete a path with its `id` |
| addText(text) | Add a text annotation to the canvas. Returns the ID of the added text. |
| updateText(text) | Update an existing text annotation on the canvas. |
| deleteText(id) | Delete a text annotation with its `id` |
| save(imageType, transparent, folder, filename, includeImage, cropToImageSize) | Save image to camera roll or filesystem. If `localSourceImage` is set and a background image is loaded successfully, set `includeImage` to true to include background image and set `cropToImageSize` to true to crop output image to background image.<br/>Android: Save image in `imageType` format with transparent background (if `transparent` sets to True) to **/sdcard/Pictures/`folder`/`filename`** (which is Environment.DIRECTORY_PICTURES).<br/>iOS: Save image in `imageType` format with transparent background (if `transparent` sets to True) to camera roll or file system. If `folder` and `filename` are set, image will save to **temporary directory/`folder`/`filename`** (which is NSTemporaryDirectory()) |
| getPaths() | Get the paths that drawn on the canvas |
| getShapes() | Get the shapes that drawn on the canvas |
| getBase64(imageType, transparent, includeImage, cropToImageSize, callback) | Get the base64 of image and receive data in callback function, which called with 2 arguments. First one is error (null if no error) and second one is base64 result. |
#### Constants
---
| Constant | Description |
| :---------- | :----------------------------------------------------------------------------------- |
| MAIN_BUNDLE | Android: empty string, '' <br/>iOS: equivalent to [[NSBundle mainBundle] bundlePath] |
| DOCUMENT | Android: empty string, '' <br/>iOS: equivalent to NSDocumentDirectory |
| LIBRARY | Android: empty string, '' <br/>iOS: equivalent to NSLibraryDirectory |
| CACHES | Android: empty string, '' <br/>iOS: equivalent to NSCachesDirectory |
### ● Using with build-in UI components
<img src="https://i.imgur.com/O0vVdD6.png" height="400" />
```javascript
import React, {Component} from 'react';
import {AppRegistry, StyleSheet, Text, View, Alert} from 'react-native';
import RNSketchCanvas from '@terrylinla/react-native-sketch-canvas';
export default class example extends Component {
render() {
return (
<View style={styles.container}>
<View style={{flex: 1, flexDirection: 'row'}}>
<RNSketchCanvas
containerStyle={{backgroundColor: 'transparent', flex: 1}}
canvasStyle={{backgroundColor: 'transparent', flex: 1}}
defaultStrokeIndex={0}
defaultStrokeWidth={5}
closeComponent={
<View style={styles.functionButton}>
<Text style={{color: 'white'}}>Close</Text>
</View>
}
undoComponent={
<View style={styles.functionButton}>
<Text style={{color: 'white'}}>Undo</Text>
</View>
}
clearComponent={
<View style={styles.functionButton}>
<Text style={{color: 'white'}}>Clear</Text>
</View>
}
eraseComponent={
<View style={styles.functionButton}>
<Text style={{color: 'white'}}>Eraser</Text>
</View>
}
strokeComponent={color => (
<View
style={[{backgroundColor: color}, styles.strokeColorButton]}
/>
)}
strokeSelectedComponent={(color, index, changed) => {
return (
<View
style={[
{backgroundColor: color, borderWidth: 2},
styles.strokeColorButton,
]}
/>
);
}}
strokeWidthComponent={w => {
return (
<View style={styles.strokeWidthButton}>
<View
style={{
backgroundColor: 'white',
marginHorizontal: 2.5,
width: Math.sqrt(w / 3) * 10,
height: Math.sqrt(w / 3) * 10,
borderRadius: (Math.sqrt(w / 3) * 10) / 2,
}}
/>
</View>
);
}}
saveComponent={
<View style={styles.functionButton}>
<Text style={{color: 'white'}}>Save</Text>
</View>
}
savePreference={() => {
return {
folder: 'RNSketchCanvas',
filename: String(Math.ceil(Math.random() * 100000000)),
transparent: false,
imageType: 'png',
};
}}
/>
</View>
</View>
);
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#F5FCFF',
},
strokeColorButton: {
marginHorizontal: 2.5,
marginVertical: 8,
width: 30,
height: 30,
borderRadius: 15,
},
strokeWidthButton: {
marginHorizontal: 2.5,
marginVertical: 8,
width: 30,
height: 30,
borderRadius: 15,
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#39579A',
},
functionButton: {
marginHorizontal: 2.5,
marginVertical: 8,
height: 30,
width: 60,
backgroundColor: '#39579A',
justifyContent: 'center',
alignItems: 'center',
borderRadius: 5,
},
});
AppRegistry.registerComponent('example', () => example);
```
#### Properties
---
| Prop | Type | Description |
| :---------------------- | :---------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| containerStyle | `object` | Styles to be applied on container |
| canvasStyle | `object` | Styles to be applied on canvas component |
| onStrokeStart | `function` | See [above](#properties) |
| onStrokeChanged | `function` | See [above](#properties) |
| onStrokeEnd | `function` | See [above](#properties) |
| onPathsChange | `function` | See [above](#properties) |
| onClosePressed | `function` | An optional function called when user taps closeComponent |
| onUndoPressed | `function` | An optional function that accepts a argument `id` (the deleted id of path) and is called when user taps "undo" |
| onClearPressed | `function` | An optional function called when user taps clearComponent |
| user | `string` | See [above](#properties) |
| closeComponent | `component` | An optional component for closing |
| eraseComponent | `component` | An optional component for eraser |
| undoComponent | `component` | An optional component for undoing |
| clearComponent | `component` | An optional component for clearing |
| saveComponent | `component` | An optional component for saving |
| strokeComponent | `function` | An optional function which accepts 1 argument `color` and should return a component. |
| strokeSelectedComponent | `function` | An optional function which accepts 3 arguments `color`, `selectedIndex`, `isColorChanged` and should return a component. `isColorChanged` is useful for animating when changing color. Because rerendering also calls this function, we need `isColorChanged` to determine whether the component is rerendering or the selected color is changed. |
| strokeWidthComponent | `function` | An optional function which accepts 1 argument `width` and should return a component. |
| strokeColors | `array` | An array of colors. Example: `[{ color: '#000000' }, {color: '#FF0000'}]` |
| defaultStrokeIndex | `numbber` | The default index of selected stroke color |
| defaultStrokeWidth | `number` | The default thickness of stroke |
| minStrokeWidth | `number` | The minimum value of thickness |
| maxStrokeWidth | `number` | The maximum value of thickness |
| strokeWidthStep | `number` | The step value of thickness when tapping `strokeWidthComponent`. |
| savePreference | `function` | A function which is called when saving image and should return an object (see [below](#objects)). |
| onSketchSaved | `function` | See [above](#properties) |
#### Methods
---
| Method | Description |
| :------------- | :-------------------- |
| clear() | See [above](#methods) |
| undo() | See [above](#methods) |
| addPath(path) | See [above](#methods) |
| deletePath(id) | See [above](#methods) |
| save() | |
#### Constants
---
| Constant | Description |
| :---------- | :---------------------- |
| MAIN_BUNDLE | See [above](#constants) |
| DOCUMENT | See [above](#constants) |
| LIBRARY | See [above](#constants) |
| CACHES | See [above](#constants) |
## Background Image
---
To use an image as background, `localSourceImage`(see [below](#background-image)) reqires an object, which consists of `filename`, `directory`(optional) and `mode`(optional). <br/>
Note: Because native module cannot read the file in JS bundle, file path cannot be relative to JS side. For example, '../assets/image/image.png' will fail to load image.
### Typical Usage
- Load image from app native bundle
- Android:
1. Put your images into android/app/src/main/res/drawable.
2. Set `filename` to the name of image files with or without file extension.
3. Set `directory` to ''
- iOS:
1. Open Xcode and add images to project by right-clicking `Add Files to [YOUR PROJECT NAME]`.
2. Set `filename` to the name of image files with file extension.
3. Set `directory` to MAIN_BUNDLE (e.g. RNSketchCanvas.MAIN_BUNDLE or SketchCanvas.MAIN_BUNDLE)
- Load image from camera
1. Retrieve photo complete path (including file extension) after snapping.
2. Set `filename` to that path.
3. Set `directory` to ''
### Content Mode
- AspectFill<br/>
<img src="https://i.imgur.com/vRydI60.png" height="200" />
- AspectFit (default)<br/>
<img src="https://i.imgur.com/r8DtgIN.png" height="200" />
- ScaleToFill<br/>
<img src="https://i.imgur.com/r9dRnAC.png" height="200" />
## Objects
---
### SavePreference object
```json5
{
folder: 'RNSketchCanvas',
filename: 'image',
transparent: true,
imageType: 'jpg',
includeImage: true,
includeText: false,
cropToImageSize: true,
}
```
| Property | Type | Description |
| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| folder? | string | Android: the folder name in `Pictures` directory<br/>iOS: if `filename` is not null, image will save to temporary directory with folder and filename, otherwise, it will save to camera roll |
| filename? | string | the file name of image<br/>iOS: Set to `null` to save image to camera roll. |
| transparent | boolean | save canvas with transparent background, ignored if imageType is `jpg` |
| imageType | string | image file format<br/>Options: `png`, `jpg` |
| includeImage? | boolean | Set to `true` to include the image loaded from `LocalSourceImage`. (Default is `true`) |
| includeImage? | boolean | Set to `true` to include the text drawn from `Text`. (Default is `true`)