best-color-picker

Best Background Picker - A Modern React Component

An advanced, feature-rich React component for selecting and customizing complex backgrounds. Built with React, TypeScript, and Tailwind CSS, this component offers a seamless user experience for creating beautiful solid colors, gradients, patterns, and image-based backgrounds with advanced effects like fades and overlays.

Features

The BgPicker component provides a comprehensive suite of tools for background creation, all accessible through a clean, modal-based interface.

• 🎨 Multiple Background Types:
  • Solid Color: A standard solid color picker with HSLA support.
  • Gradient Picker: Create Linear, Radial, and Conic gradients with multi-stop and angle controls.
  • Mesh Gradient: Generate stunning, smooth mesh gradients with up to 6 customizable color stops.
  • Pattern Picker: Apply SVG-based patterns with customizable background and pattern colors, and size control.
  • Image Picker: Use images as backgrounds, with support for local uploads and Unsplash (via best-img-uploader).
• ✨ Advanced Effects:
  • Fades: Apply beautiful gradient masks over any background for elegant fade effects, perfect for improving text readability. Supports a special "Blurred Image" mode that uses a blurred version of the main background image.
  • Overlays: Layer colors and gradients over the background with a wide range of mix-blend-mode options or simple opacity adjustments.
• 🛠️ Powerful Color Tools:
  • Eye Dropper: Pick colors directly from anywhere on the screen.
  • Color Matching: Automatically extract color palettes from images on the page to create harmonious designs.
  • Color Harmonies: Generate analogous, triadic, and tetradic color combinations, plus tones from any selected color.
  • Hue Shifting: Easily shift the hue of all colors in a gradient or pattern simultaneously.
• 🖼️ Image Customization:
  • Control background size (cover, contain, auto, px), repeat, and position.
  • Apply various levels of blur directly to the background image.
• ⬇️ Download Functionality:
  • Export the created background as a high-quality PNG image using html-to-image.

Demo Application

The project includes a demo application located in the /app directory, which showcases a live implementation of the BgPicker component.

Running the Demo

• Clone the repository:

  git clone <repository-url> my-project
  cd my-project
  

• Install dependencies:

  yarn install
  

• Start the development server:

  yarn dev
  

  The demo will be running at http://localhost:5173.

Usage

Integrate the BgPicker component into your React application by importing it and providing the necessary state management for its values.

import { useState } from 'react';
import BgPicker, {
	Style,
	Value,
	FadeValue,
	OverlayValue
} from '@/src/bg-picker';

const YourComponent = () => {
	const [value, setValue] = useState<Value | null>({
		type: 'solid',
		color: 'hsl(0, 0%, 100%)'
	});
	const [style, setStyle] = useState<Style>({});
	const [fadeValue, setFadeValue] = useState<FadeValue | null>(null);
	const [overlayValue, setOverlayValue] = useState<OverlayValue | null>(null);

	// The `onChange` callback provides all the derived styles.
	const [fadeStyle, setFadeStyle] = useState<FadeStyle | null>(null);
	const [overlayStyle, setOverlayStyle] = useState<OverlayStyle | null>(null);

	return (
		<div id='main-container'>
			{/* This is the element that will display the background */}
			<div
				id='canvas'
				style={style}
			>
				{/* Apply overlay and fade styles if they exist */}
				{overlayStyle && <div style={overlayStyle} />}
				{fadeStyle && (
					<div style={fadeStyle.mask}>
						<div style={fadeStyle.background} />
					</div>
				)}
			</div>

			<BgPicker
				container='#main-container' // For color matching
				fadeValue={fadeValue}
				imgProxyUrl='http://localhost:5174/img/proxy'
				imgUnsplashApiUrl='http://localhost:5174/img/unsplash'
				imgUploadApiUrl='http://localhost:5174/img/upload'
				onChange={({
					value,
					style,
					fadeValue,
					fadeStyle,
					overlayValue,
					overlayStyle
				}) => {
					setValue(value);
					setStyle(style);
					setFadeValue(fadeValue);
					setFadeStyle(fadeStyle);
					setOverlayValue(overlayValue);
					setOverlayStyle(overlayStyle);
				}}
				overlayValue={overlayValue}
				value={value}
			>
				{/* This is the trigger button for the picker */}
				{({ open, style: triggerStyle }) => (
					<button onClick={open}>
						<span>Background</span>
						<div style={triggerStyle} />
					</button>
				)}
			</BgPicker>
		</div>
	);
};

API Reference

<BgPicker /> Props

| Prop | Type | Description | | :-------------------- | :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | value | Value | null | (Controlled) The current background value object (solid, gradient, etc.). | | fadeValue | FadeValue | null | (Controlled) The current fade configuration object. | | overlayValue | OverlayValue | null | (Controlled) The current overlay configuration object. | | onChange | (data: OnChangeData) => void | Callback fired when any value changes. It returns all values and their corresponding CSS style objects. See OnChangeData section below. | | children | ({ open, style, value }) => React.ReactElement | A render prop function to render the trigger element. open is a function to open the picker, and style is a CSS object for a preview thumbnail. | | container | HTMLElement | string | Optional. A selector or element reference for the area where image-based color matching should search for <img> tags. Defaults to document.body. | | defaultValue | Value | The initial value for the background if value is null. | | defaultFadeValue | FadeValue | The initial value for the fade if fadeValue is null. | | defaultOverlayValue | OverlayValue | The initial value for the overlay if overlayValue is null. | | imgProxyUrl | string | The URL for the image proxy server. | | imgUnsplashApiUrl | string | The URL for the image Unsplash API. | | imgUploadApiUrl | string | The URL for the image upload endpoint. |

onChange Callback Data

The onChange callback receives a single object with the following properties:

Property	Type	Description
value	Value	The current main background value object.
style	Style	The CSS style object for the main background.
fadeValue	FadeValue	The current fade value object.
fadeStyle	FadeStyle	The CSS style objects for rendering the fade effect.
overlayValue	OverlayValue	The current overlay value object.
overlayStyle	OverlayStyle	The CSS style object for the overlay.

Data Structures

Below are examples of the value, fadeValue, and overlayValue objects.

Value Object Examples

// Solid
{
  type: 'solid',
  color: 'hsl(0, 0%, 100%)'
}

// Linear Gradient
{
  type: 'linear-gradient',
  angle: 90,
  stops: [
    { id: 'stop-1', color: 'hsl(160, 100%, 32%)', position: 0 },
    { id: 'stop-2', color: 'hsl(200, 100%, 59%)', position: 100 }
  ]
}

// Image
{
  type: 'img',
  src: 'https://images.unsplash.com/...',
  blur: 'none', // 'light', 'medium', 'heavy', 'hyper'
  position: 'center center',
  repeat: 'no-repeat',
  size: 'cover' // 'auto', 'contain', or a number for pixels
}

// Mesh Gradient
{
  type: 'mesh-gradient',
  backgroundColor: 'hsl(0, 0%, 0%)',
  stops: [
    { id: 'stop-1', color: 'hsl(232, 66%, 66%)', x: 20, y: 20, radius: 75 },
    { id: 'stop-2', color: 'hsl(270, 40%, 58%)', x: 80, y: 30, radius: 75 }
  ]
}

FadeValue Object Example

{
  mode: 'custom-100', // 'none', 'blurred-img', 'custom-100', 'custom-80', etc.
  mask: {
    angle: 0,
    stops: [50, 70] // [start %, end %]
  },
  // The background for the fade can be any `Value` type
  background: {
    type: 'solid',
    color: 'hsl(0, 0%, 13%)'
  }
}

OverlayValue Object Example

{
  mode: 'multiply', // 'none', 'custom-25', or any OverlayMixBlendMode
  // The background for the overlay can be any `Value` type
  background: {
    type: 'solid',
    color: 'hsl(0, 0%, 13%)'
  }
}

Author

Felipe Rohde

• Twitter: @felipe_rohde
• Github: @feliperohdee
• Email: [e-mail]