zignis / react-eyedrop

Seamlessly integrate a static typed, fully-tested color-picking React component/hook!

React EyeDrop

A highly customizable, fully typed & tested color eye-dropper for your React project.

With flexibility in mind, let your users eye drop anything in your app within a minute.

React Component or React Hook, you have both at your disposal.

A example project is included for basic usage of both Component & Hook.

Credits to Sharon for such splendid taste in color.

Installation

Yarn:

yarn add react-eyedrop

NPM:

npm install --save react-eyedrop

API Reference

Table of contents

• React Component
  • onChange
    
  • wrapperClasses
    
  • buttonClasses
    
  • customComponent
    
  • customProps
    
  • colorsPassThrough
    
  • disabled
    
  • once
    
  • pickRadius
    
  • cursorActive
    
  • cursorInactive
    
  • onInit
    
  • onPickStart
    
  • onPickEnd
    
• React Hook
  • Usage

React Component

onChange

required

Expects function

Returns an object:

Available properties{ rgb: string, hex: string, customProps: object }

This returns the picked color data and the user's passed in data object, see customProps for usage.

Example:

function onChange({ rgb, hex }) {
    /* Do stuff */
}
<!-------->
<EyeDropper onChange={onChange} />

wrapperClasses

Expects string

Example:

<EyeDropper wrapperClasses="my-css-class" />
/* or even */
<EyeDropper wrapperClasses={`my-css-class ${active ? 'my-active-css-class' : ''}`} />

buttonClasses

Expects string

Example:

<EyeDropper buttonClasses="my-css-class" />
/* or even */
<EyeDropper buttonClasses={`my-css-class ${active ? 'my-active-css-class' : ''}`} />

customComponent

Expects React Node

Use your own component for your EyeDropping business.

Use the onClick prop which gets passed down.

Example:

const Button = ({ onClick }) => 
    <button className="btn" onClick={onClick} >My custom button</button>
<!-------->
<EyeDropper customComponent={Button} />

customProps

Expects object

Requires customComponent to be set

User can pass in their own data to the customComponent, the data can then be retrieved along with the color values in the onChange handler.

Example:

const onChange = ({ rgb, hex, customProps }) => {
    const { data1, data2, } = customProps
}
<!-------->
<Eyedropper customComponent={Button} customProps={{data1, data2, data3}} onChange={onChange}/>

colorsPassThrough

Expects string

Provides access to the picked color value object { rgb, hex } for the eyedropper component.

Name provided here will be the name of the color object

Example:

const Button = ({ onClick, pixelColors }) => 
    <button className="btn" onClick={onClick} style={{backgroundColor: pixelColors.hex}}>My custom button</button>
<!-------->
<EyeDropper customComponent={Button} colorsPassThrough='pixelColors' />

disabled

Expects boolean

Internal property provided by the eyedropper component for passing down to the customComponent. It gives control disabling the button element while color picking is active

Example:

const Button = ({ onClick, disabled }) => 
    <button className="btn" onClick={onClick} disabled={disabled} >My custom button</button>

once

Expects boolean

Defaults to true

Decide if EyeDropping should stop after having pressed once. Dynamically changing this property during runtime will remove event listener & set cursorInactive. (if false -> true during runtime)

Example:

<EyeDropper once />

/* or */

<EyeDropper once={false} />

pickRadius

Expects number

Range 0-450

Size of the pick radius. The final value will be the average sum of all the pixels within the radius.

radius = 1 <=> 3 x 3 blocks <=> 9 pixels

radius = 2 <=> 5 x 5 blocks <=> 25 pixels

radius = 3 <=> 7 x 7 blocks <=> 49 pixels

Example:

<EyeDropper pickRadius={1} />

cursorActive

Expects string

Defaults to copy

Decide what CSS cursor to use when actively EyeDropping.

Link to CSS Cursors

Example:

<EyeDropper cursorActive="cursor" />

cursorInactive

Expects string

Defaults to auto

Decide what CSS cursor to revert back to once finished with EyeDropping business.

Link to CSS Cursors

Example:

<EyeDropper cursorActive="auto" />

onInit

Expects function

Callback for componentDidMount

Example:

function getPeanut() {
    console.log('Mmm... Definately overrated.')
}

<!-------->

<EyeDropper onInit={getPeanut} />
/* Will be called when component is mounted */

onPickStart

Expects function

Callback for when you start Eyedropping

Example:

function getBananas() {
    console.log('Ahhh... Much better.')
}

<!-------->

<EyeDropper onPickStart={getBananas} />

/* Will be called when starting to EyeDrop */

onPickEnd

Expects function

Callback for when you stop EyeDropping

Example:

function buyBurritos() {
    console.log('Yum!')
}

<!-------->

<EyeDropper onPickEnd={buyBurritos} />

/* Will be called when you finish EyeDropping */

React Hook

Usage

colors will contain whatever is clicked once pickColor is called.
Call cancelPickColor to stop picking colors. 🤪

Example:

import { useEyeDrop } from 'react-eyedrop'

const [colors, pickColor, cancelPickColor] = useEyeDrop({
  once: boolean,
  pickRadius: number,
  cursorActive: CSS Cursors,
  cursorInactive: CSS Cursors,
  onPickStart?: () => void
  onPickEnd?: () => void
  onPickCancel?: () => void
})

Link to CSS Cursors

Development setup

Run the unit tests locally:

npm i
/* or */
yarn

/* and then */

npm run test

Release History

• 5.4.2
  • Fixed bug with color picking HTML elements
  • Now functions with React 18
• 5.4.1
  • Added onPickStart, onPickEnd and onPickCancel to hook
• 5.3.0
  • Now handles any HTML element with background property
• 5.2.1
  • Added onPickEnd property
• 5.1.3
  • Pretty serious bugfix
• 5.0.4
  • Rewritten in TypeScript
  • Introduced useEyeDrop React hook
• 4.2.0
  • Fixed fundamental issue with color picking
  • Now handles cross-origin images
• 4.1.3
  • Bug fix related to color picking from the correct target
• 4.1.2
  • No longer inline styling
• 4.1.1
  • Added Unit test Coverage badges in README
• 4.1.0
  • 100% Unit Test Coverage
• 4.0.0
  • Removed property onPickEnd since same functionality can be achieved with handleChange
• 3.4.2
  • Now supports color-picking images presented through img tags on the DOM
• 3.0.0
  • Updated pickRadius feature to work with different units; radius & pixel.
• 2.1.2
  • Fixed a typo in documentation
• 2.1.1
  • Added pickRadius feature
• 2.0.1
  • Updated documentation
• 2.0.0
  • Changed prop name from buttonComponent to customComponent
• 1.0.0
  • Initial release

Meta

Manjodh "Mango" Singh – [email protected]

Distributed under the MIT license. See license for more information.

https://github.com/jodhman/

Contributing

1. Fork it (https://github.com/jodhman/react-eyedrop/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request