usb-paint

English | 简体中文

USB-Paint

A universal (Universal), simple (Simple), and beautiful (Beautiful) Hand-drawn style painting tool component—USB-Paint. You can think of it as a plug-and-play drawing panel tool, like the ubiquitous USB interface, which can be quickly integrated into any frontend project (native HTML, Vue, React, Svelte, Angular).

Features

• Universal: Supports multiple frontend frameworks, such as native HTML, Vue, React, Svelte, and Angular
• Simple: Clean page structure with no complex styles or logic
• Beautiful: Attractive UI design with multi-color/style options and customization support
• Hand-drawn style
• Supports various drawing tools, including brush, eraser, clear, and export image functions

Installation & Usage

Method 1: Using npm/yarn (Recommended)

Installation

npm install usb-paint
or
yarn add usb-paint

Usage

Note: When using it within a framework, ensure the DOM is fully loaded before accessing it. For example, in Vue, initialize it in the onMounted or later lifecycle hooks.

import USBPaint from "usb-paint";

new USBPaint({
  target: document.querySelector("#root"),
});

Method 2: Using CDN, directly inserted into HTML

<script src="https://cdn.jsdelivr.net/npm/usb-paint@latest/dist/usbpaint.iife.js" type="text/javascript"></script>
<script>
  let a = new USBPaint({
    target: document.querySelector("#root"),
  });
</script>

Parameter Details

Parameter Example

import USBPaint from "usb-paint";

new USBPaint({
  target: document.querySelector("#root"),
  lineOptions: {
    lineWidth: 8,
    lineColor: "red",
    lineAlpha: 1,
    lineSmooth: 1,
    lineThin: 0.6,
    lineStream: 1,
    lineStart: 0,
    lineEnd: 80,
  },
  showTools: true,
  toolsConfig: {
    tools: "all", // ["eraser", "paint", "trash", "export" ],
    position: {
      x: 400,
      y: 400,
      direction: "column", // column row
    },
    iconsConfig: {
      size: 20,
      width: 0.5,
      color: "red",
      fill: "black",
    },
    backgroud: {
      color: "blue",
      border: "1px solid red",
      radius: 10,
    },
  },
  background: "black",
});

Primary Parameters

Parameter	Required	Type	Default	Description
target	No	HTMLElement	body element	Target container, can be a DOM element or CSS selector
lineOptions	No	LineOptionsType	(Details below)	Configuration for brush line
showTools	No	boolean	false	Show toolbar or not
toolsConfig	No	ToolsConfigType	(Details below)	Toolbar configuration when showTools is true
background	No	string	-	Transparent by default; accepts Hex/RGB/HSL/HSB/color names (e.g., red)

Secondary Parameters

LineOptionsType

Parameter	Required	Type	Default	Description
lineWidth	No	number	4	Brush line width
lineColor	No	string	#000	Brush line color; accepts Hex/RGB/HSL/HSB/color names
lineAlpha	No	number	1	Brush line opacity
lineSmooth	No	number	1	Softness of the brush line edges
lineThin	No	number	0.6	Brush pressure's effect on stroke size
lineStream	No	number	1	Degree of stroke simplification
lineStart	No	number	0–100	Tapering at the start of the line
lineEnd	No	number	0–100	Tapering options at the end of the line

ToolsConfigType

Parameter	Required	Type	Default	Description
tools	No	string/ array	all	Toolbar tools; accepts any combination of ["eraser", "paint", "trash", "export"]; "[]" hides toolbar, "all" shows all
position	No	string/AxisType	top	Toolbar position; accepts "left"/"right"/"top"/"bottom" or AxisType position data (detailed below)
iconsConfig	No	object	-	Icon configuration for the toolbar
backgroud	No	object	-	Background configuration for the toolbar

Tertiary Parameters

toolsConfig.position (AxisType)

Parameter	Required	Type	Default	Description
x	Yes	number	-	Horizontal coordinate (px)
y	Yes	number	-	Vertical coordinate (px)
direction	Yes	string	-	Arrangement direction: row/column

toolsConfig.iconsConfig

Parameter	Required	Type	Default	Description
size	No	number	20	Icon size (px)
width	No	number	1.25	Icon line width
color	No	string	#000	Icon line color; accepts Hex/RGB/HSL/HSB/color names
fill	No	string	none	Icon fill color; accepts Hex/RGB/HSL/HSB/color names, "none" for no fill by default

toolsConfig.background

Parameter	Required	Type	Default	Description
color	No	string	#fff	Background color; accepts Hex/RGB/HSL/HSB/color names
border	No	string	1px solid rgba(0,0,0,0.1)	Border (CSS format)
radius	No	number	10	Border radius

Event Triggers

Event Name	Description	Return Data
exportToImage	Export image data	base64
eraserTool	Eraser	-
freeDrawTool	Drawing	-
clearTool	Clear	-

Event Trigger Example

import USBPaint from "usb-paint";

const usbPaint = new USBPaint();
// Trigger image export
usbPaint.exportToImage();
// Activate eraser tool
usbPaint.eraserTool();
// Activate drawing tool
usbPaint.freeDrawTool();
// Clear the canvas
usbPaint.clearTool();