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.
Sharon for such splendid taste in color.
Credits toInstallation
Yarn:
yarn add react-eyedrop
NPM:
npm install --save react-eyedrop
API Reference
Table of contents
- React Component
- React Hook
React Component
onChange
required
function
Expects Returns an object:
{ rgb: string, hex: string, customProps: object }
Available propertiesThis 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
string
Expects Example:
<EyeDropper wrapperClasses="my-css-class" />
/* or even */
<EyeDropper wrapperClasses={`my-css-class ${active ? 'my-active-css-class' : ''}`} />
buttonClasses
string
Expects Example:
<EyeDropper buttonClasses="my-css-class" />
/* or even */
<EyeDropper buttonClasses={`my-css-class ${active ? 'my-active-css-class' : ''}`} />
customComponent
React Node
Expects Use your own component for your EyeDropping business.
onClick
prop which gets passed down.
Use the Example:
const Button = ({ onClick }) =>
<button className="btn" onClick={onClick} >My custom button</button>
<!-------->
<EyeDropper customComponent={Button} />
customProps
object
Expects 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
string
Expects 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
boolean
Expects 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
boolean
Expects true
Defaults to false
-> true
during runtime)
Decide if EyeDropping should stop after having pressed once. Dynamically changing this property during runtime will remove event listener & set cursorInactive. (if Example:
<EyeDropper once />
/* or */
<EyeDropper once={false} />
pickRadius
number
Expects 0-450
Range 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
string
Expects copy
Defaults to Decide what CSS cursor to use when actively EyeDropping.
Link to CSS Cursors
Example:
<EyeDropper cursorActive="cursor" />
cursorInactive
string
Expects auto
Defaults to Decide what CSS cursor to revert back to once finished with EyeDropping business.
Link to CSS Cursors
Example:
<EyeDropper cursorActive="auto" />
onInit
function
Expects Callback for componentDidMount
Example:
function getPeanut() {
console.log('Mmm... Definately overrated.')
}
<!-------->
<EyeDropper onInit={getPeanut} />
/* Will be called when component is mounted */
onPickStart
function
Expects 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
function
Expects 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
})
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
- Added
- 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
- Removed property
- 3.4.2
- Now supports color-picking images presented through
img
tags on the DOM
- Now supports color-picking images presented through
- 3.0.0
- Updated
pickRadius
feature to work with different units; radius & pixel.
- Updated
- 2.1.2
- Fixed a typo in documentation
- 2.1.1
- Added
pickRadius
feature
- Added
- 2.0.1
- Updated documentation
- 2.0.0
- Changed prop name from
buttonComponent
tocustomComponent
- Changed prop name from
- 1.0.0
- Initial release
Meta
Manjodh "Mango" Singh – [email protected]
Distributed under the MIT license. See license for more information.
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