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
- React Hook
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. :zany_face:
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
- 5.1.3
- 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
- 4.1.1
- Added Unit test Coverage badges in README
- 4.1.0
- 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
- 2.0.1
- 2.0.0
- Changed prop name from
buttonComponent
to customComponent
- 1.0.0
Meta
Manjodh "Mango" Singh – manjodheriksingh@gmail.com
Distributed under the MIT license. See license for more information.
https://github.com/jodhman/
Contributing
- Fork it (https://github.com/jodhman/react-eyedrop/fork)
- Create your feature branch (
git checkout -b feature/fooBar
) - Commit your changes (
git commit -am 'Add some fooBar'
) - Push to the branch (
git push origin feature/fooBar
) - Create a new Pull Request