Gradient Picker
A powerful and customizable gradient picker for modern web applications
## Features
- 🎨 Intuitive color stop management
- 📐 Support for linear and radial gradients
- 🔄 Multiple direction modes (select or degree)
- 💾 Flexible output formats (CSS string, object, or stops list)
- 📱 Mobile-friendly with touch support
- 🎯 Precise control with numeric inputs
- 🖼️ Optional preview window
- 🌈 Comprehensive color format support (Hex, RGB, HSL, Named Colors)
- 🔍 CSS gradient string parsing
- 💨 Performance optimized with color caching
- ✅ Built-in validation
- 📝 Named color support (140+ CSS colors)
- 🎨 Customizable styles
## Installation
```bash
npm install @ldrender/gradient-picker
```
## Development
```bash
# Start development server
npm run dev
# Build for production
npm run build
```
## Quick Start
```javascript
import GradientPicker from '@ldrender/gradient-picker';
import '@ldrender/gradient-picker/dist/gradient-picker.css';
const gradientPicker = new GradientPicker({
el: '#gradient-picker',
preview: true,
stops: [
{ color: '#ff0000', offset: 0 },
{ color: 'rgb(0, 255, 0)', offset: 33 },
{ color: 'blue', offset: 66 },
{ color: 'hsl(270, 100%, 50%)', offset: 100 }
]
});
```
## Configuration
### Constructor Options
```typescript
interface GradientPickerProps {
el: string; // Selector for the target element
stops?: GradientStop[]; // Initial color stops
type?: 'linear' | 'radial'; // Gradient type (default: 'linear')
direction?: string | number; // Gradient direction (default: 'right')
directionType?: 'select' | 'percent'; // Direction input type (default: 'select')
directionRadial?: boolean; // For gradient type 'radial', select if direction input is displayed (default: true)
returnType?: 'string' | 'object' | 'stops-list'; // Output format (default: 'string')
preview?: boolean; // Enable preview window (default: false)
}
interface GradientStop {
color: string; // CSS color value
offset: number; // Position in percentage (0-100)
id: number; // Unique identifier
}
```
### Return Types
- `string`: CSS gradient string
- `object`: Gradient configuration object
- `stops-list`: Array of color stops only
## Methods
### Core Methods
#### getGradient()
Returns the gradient configuration as an object.
```typescript
interface GradientObject {
type: 'linear' | 'radial';
direction: string | number;
stops: Array<{ color: string; offset: number; }>;
}
```
#### getStops()
Returns an array of color stops.
#### addColorStop(color: string, offset: number)
Adds a new color stop to the gradient.
### Additional Methods
#### importFromCSSString(gradientStr: string)
Parses and imports a CSS gradient string.
```javascript
gradientPicker.importFromCSSString('linear-gradient(to right, #ff0000 0%, #00ff00 50%)');
```
#### initDirection(directionType: 'select' | 'percent')
Changes the direction input type dynamically.
## Events
### Change Event
Fired whenever the gradient is modified:
```javascript
document.querySelector('#gradient-picker').addEventListener('change', (event) => {
const value = event.target.value;
// value format depends on returnType option
});
```
### Error Handling
The picker includes built-in validation for:
- Color formats
- Stop positions (0-100)
- Minimum number of stops (2)
- Direction values
```javascript
try {
gradientPicker.addColorStop('invalid-color', 50);
} catch (error) {
console.error('Invalid color format');
}
```
## Gradient Type Support
### Linear Gradients
- integer: `0 - 360`
- string: `top`, `right`, `bottom`, `left`
### Radial Gradients
- string: `top`, `right`, `bottom`, `left`, `center`
- integer: `0` = `at center`
- integer: `1 - 89` = `at center top`
- integer: `90 - 179` = `at center right`,
- integer: `180 - 269` = `at center bottom`,
- integer: `270 - 359` = `at center left`
- integer: `360` = `at center top`
## Color Support
### Supported Formats
- Hexadecimal: `#ff0000`, `#f00`
- RGB/RGBA: `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)`
- HSL/HSLA: `hsl(0, 100%, 50%)`, `hsla(0, 100%, 50%, 0.5)`
- Named Colors: `red`, `blue`, `forestgreen`, etc.
#### Examples
```javascript
// Hexadecimal
gradientPicker.addColorStop('#ff0000', 0); // Standard hex
gradientPicker.addColorStop('#f00', 0); // Short hex
// RGB/RGBA
gradientPicker.addColorStop('rgb(255, 0, 0)', 0);
gradientPicker.addColorStop('rgba(255, 0, 0, 0.5)', 0);
// HSL/HSLA
gradientPicker.addColorStop('hsl(0, 100%, 50%)', 0);
gradientPicker.addColorStop('hsla(0, 100%, 50%, 0.5)', 0);
// Named Colors
gradientPicker.addColorStop('red', 0);
gradientPicker.addColorStop('blue', 50);
gradientPicker.addColorStop('green', 100);
```
### Color Caching
The picker includes an optimized color normalization system with caching for improved performance.
### Named Colors
Supports all standard CSS color names (140+ colors). Full list available in the source code.
Named Colors List supporter
## Styling Customization
The picker includes a default stylesheet that can be customized to match your application's design.
You must use the following variables :
(You can override the default styles by defining these variables in your own stylesheet)
```css
.gradient-picker {
--gradient-picker-box-shadow: inset 0 0 0.5px 1px hsla(0, 0%, 100%, 0.1),
0 0 0 1px hsla(230, 13%, 9%, 0.075),
0 0.3px 0.4px hsla(230, 13%, 9%, 0.02),
0 0.9px 1.5px hsla(230, 13%, 9%, 0.045),
0 3.5px 6px hsla(230, 13%, 9%, 0.09);
--gradient-picker-preview-height: 120px;
--gradient-picker-input-height: 36px;
--gradient-picker-input-padding: 0.5rem;
--gradient-picker-input-border: unset;
--gradient-picker-handler-border: solid 3px rgb(61, 61, 61);
--gradient-picker-line-height: 36px;
--gradient-picker-font-size: 14px;
--gradient-picker-border-radius: 8px;
--gradient-picker-focus-outline: none;
--gradient-picker-focus-box-shadow: 0 0 0 2px rgb(0, 95, 204);
--gradient-picker-focus-border-color: rgb(0, 95, 204);
--gradient-picker-remover-color: #555;
--gradient-picker-remover-color-hover: rgb(229, 64, 64);
--gradient-picker-background-color: #fff;
--gradient-picker-color: #000;
}
```
## Browser Support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Android Chrome)
## Performance Considerations
- Efficient color caching system
- Debounced updates for smooth interactions
- Optimized DOM manipulation
- Event delegation for color stops
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the LICENSE file for details.