Skip to content

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

Notifications You must be signed in to change notification settings

jodhman/react-eyedrop

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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.

Example:

<EyeDropper cursorActive="cursor" />

cursorInactive

Expects string
Defaults to auto
Decide what CSS cursor to revert back to once finished with EyeDropping business.

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 – manjodheriksingh@gmail.com

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