just_color_picker 0.5.0

A customizable HSV color picker with circular hue wheel, saturation-value panel, alpha slider, and color conversion utilities. No external dependencies.

just_color_picker

A customizable HSV color picker for Flutter with a circular hue wheel, saturation-value panel, alpha slider, and color conversion utilities. Zero external dependencies — built entirely with CustomPainter.

Features

• Two layout styles — circular wheel or linear bar, switchable via ColorPickerType
• Circular Hue Wheel with embedded SV (Saturation-Value) Panel
• Linear Hue Bar with standalone square SV Panel
• Alpha Slider with checkerboard transparency background
• Color conversion utilities — HEX, RGB, HSL with alpha support
• Uncontrolled and controlled modes
• Fully customizable sizes and visibility toggles

Getting Started

Add the dependency:

dependencies:
  just_color_picker: ^0.5.0

Usage

Wheel Mode (default)

import 'package:just_color_picker/just_color_picker.dart';

JustColorPicker(
  initialColor: Colors.blue,
  onColorChanged: (Color color) {
    // Called continuously during drag
  },
  onColorChangeEnd: (Color color) {
    // Called when drag ends
  },
)

Bar Mode

JustColorPicker(
  type: ColorPickerType.bar,
  initialColor: Colors.blue,
  onColorChanged: (color) {},
)

Controlled Mode

JustColorPicker(
  color: myColor,          // externally managed
  onColorChanged: (color) {
    setState(() => myColor = color);
  },
)

The picker shows color and nothing else. A drag proposes a color through onColorChanged, and the picker moves only when you pass a color back. To reject a change, keep color as it is. To constrain it, for example by snapping to a palette, pass back the adjusted color. Hue and saturation survive grey and black as long as you pass the proposed color back unchanged.

If you only need the final value and do not rebuild on every change (for example in a dialog), use initialColor instead.

Customization

JustColorPicker(
  initialColor: Colors.red,
  onColorChanged: (color) {},
  type: ColorPickerType.wheel, // wheel or bar
  wheelDiameter: 300,          // wheel / SV panel size
  wheelWidth: 30,              // ring thickness (wheel mode)
  thumbRadius: 10,             // indicator size
  showAlpha: true,             // alpha slider
)

Color Conversion Utilities

// HEX
final hex = colorToHex(color);                        // "FF5733"
final hexAlpha = colorToHex(color, includeAlpha: true); // "80FF5733"
final color = hexToColor('#FF5733');
final valid = isValidHex('#FF5733');

// RGB
final rgb = colorToRgb(color);   // (r: 255, g: 87, b: 51, a: 255)
final color = rgbToColor(255, 87, 51);
final color = rgbToColor(255, 87, 51, 128); // with alpha

// HSL
final hsl = colorToHsl(color);   // (h: 11.0, s: 100.0, l: 60.0, a: 255)
final color = hslToColor(11, 100, 60);
final color = hslToColor(11, 100, 60, 128); // with alpha

Picker Types

ColorPickerType.wheel

Circular hue ring with a saturation-value panel inscribed inside. Classic HSV wheel layout.

ColorPickerType.bar

Square SV panel on top with a horizontal hue bar below it. Compact linear layout.

API

JustColorPicker

Parameter	Type	Default	Description
initialColor	Color?	—	Initial color (uncontrolled mode)
color	Color?	—	Controlled color
onColorChanged	ValueChanged<Color>	required	Real-time color callback
onColorChangeEnd	ValueChanged<Color>?	null	Gesture-end callback
type	ColorPickerType	wheel	Layout style (wheel or bar)
wheelDiameter	double	280.0	Wheel diameter / SV panel size
wheelWidth	double	26.0	Ring thickness (wheel mode only)
showAlpha	bool	true	Show alpha slider
thumbRadius	double	8.0	Thumb indicator radius

ColorState

Property / Method	Type	Description
ColorState.fromColor(Color)	factory	Create from a Flutter Color
ColorState.fromHSV(HSVColor)	factory	Create from an HSVColor
ColorState.fromAHSV(a, h, s, v)	factory	Create from individual components
hue	double	Hue (0–360)
saturation	double	Saturation (0–1)
value	double	Value / brightness (0–1)
alpha	double	Alpha (0–1)
hsv	HSVColor	Underlying HSVColor
toColor()	Color	Convert to Flutter Color
withHue(double)	ColorState	Copy with new hue
withSV(double, double)	ColorState	Copy with new saturation & value
withAlpha(double)	ColorState	Copy with new alpha

Standalone Widgets

These widgets are also exported for custom layouts:

Widget	Description
HueWheel	Circular hue ring with embedded SV panel
HueBar	Horizontal hue spectrum slider
SvPanel	Saturation-value rectangle
AlphaSlider	Opacity slider with checkerboard background

ColorState

Immutable wrapper around HSVColor with convenience methods for color manipulation.

// Create from a Color or HSV components
final state = ColorState.fromColor(Colors.blue);
final state = ColorState.fromHSV(myHsvColor);
final state = ColorState.fromAHSV(1.0, 210, 0.8, 0.9);

// Read components
state.hue;        // 0–360
state.saturation;  // 0–1
state.value;       // 0–1
state.alpha;       // 0–1
state.hsv;         // underlying HSVColor

// Immutable updates
final updated = state.withHue(120).withSV(0.5, 0.8).withAlpha(0.9);

// Convert back to Color
final color = state.toColor();

Conversion Utilities

Function	Description
colorToHex(Color, {includeAlpha})	Color → "FF5733"
hexToColor(String)	"#RGB" / "#RRGGBB" / "#AARRGGBB" → Color?
isValidHex(String)	HEX string validation
colorToRgb(Color)	Color → ({int r, int g, int b, int a})
rgbToColor(int r, int g, int b, [int a])	RGB → Color
colorToHsl(Color)	Color → ({double h, double s, double l, int a})
hslToColor(double h, double s, double l, [int a])	HSL → Color

Example

The example/ directory contains an interactive playground app where you can toggle all options in real time. Run it with:

cd example
flutter run