palette

pub package

A package for creating, generating, and interfacing with color palettes.

palette is built on top of the color_models package, which exposes models for the CMYK, HSI, HSL, HSP, HSB, LAB, Oklab, RGB, and XYZ color spaces.

For use with Flutter, see: https://pub.dev/packages/flutter_palette

Usage

import 'package:palette/palette.dart`;

Creating Palettes

A ColorPalette can be created directly by constructing it with a list of ColorModels, or can be generated with one of its factory constructors.

ColorPalette has 6 factory constructors: empty, adjacent, polyad, random, splitComplimentary, and opposites.

Note: As of v1.1.0, ColorPalette implements List<ColorModel>.

// Create a color palette with a set of pre-defined colors.
ColorPalette(<ColorModel>[
  RgbColor(0, 0, 0), // Black
  RgbColor(144, 144, 144), // Grey
  RgbColor(255, 255, 255), // White
  RgbColor(255, 0, 0), // Red
  RgbColor(0, 255, 0), // Green
  RgbColor(0, 0, 255), // Blue
  RgbColor(255, 255, 0), // Yellow
  RgbColor(0, 255, 255), // Cyan
  RgbColor(255, 0, 255), // Magenta
]);

/// Create an empty color palette.
ColorPalette.empty();

/// Generate a color palette with 3 colors by selecting
/// the colors 60° to either side of the base color.
ColorPalette.adjacent(
  RgbColor(255, 0, 0),
  numberOfColors: 3,
  distance: 60,
);

/// Generate a color palette with 5 colors by evenly spacing the colors around the
/// color wheel from the base color, with a variation of 15° in the generated hues,
/// and a variation of 10% in the generated saturation and brightness values from the
/// base color's values.
ColorPalette.polyad(
  CmykColor(100, 50, 0, 0),
  numberOfColors: 5,
  hueVariability: 15,
  saturationVariability: 10,
  brightnessVariability: 10,
);

/// Generate a color palette with 8 colors at random.
///
/// By default, [distributeHues] is set to `true`, which will distribute the
/// hues of the generated colors around the color wheel.
///
/// The [distributionVariability] parameter defaults to:
/// `(minHue - maxHue).abs() / numberOfColors / 4`, set it to `0` to space the
/// colors around the wheel completely evenly.
ColorPalette.random(8, distributionVariability: 0);

/// Generate a color palette with 8 colors with completely random values.
ColorePalette.random(8, distributeHues: false);

/// Generate a color palette with 5 colors by selecting colors distributed
/// to either side of the color opposite of the base color. The distance
/// between the selected colors' hues defaults to 30°. Variability to the
/// hue, saturation, and brightness values can also be added with their
/// respective parameters.
ColorPalette.splitComplimentary(
  HslColor(150, 60, 100),
  numberOfColors: 5,
);

/// Generates a color palette containing all of the colors contained
/// in [colorPalette], as well as their opposite colors.
ColorPalette.opposites(colorPalette);

Colors

The color palette can be viewed as a List&lt;ColorModel&gt; by referencing the colors getter.

// Construct a [ColorPalette] from a list of [RgbColor]s.
final colorPalette = ColorPalette(<ColorModel>[
  RgbColor(0, 0, 0), // Black
  RgbColor(144, 144, 144), // Grey
  RgbColor(255, 255, 255), // White
  RgbColor(255, 0, 0), // Red
  RgbColor(0, 255, 0), // Green
  RgbColor(0, 0, 255), // Blue
  RgbColor(255, 255, 0), // Yellow
  RgbColor(0, 255, 255), // Cyan
  RgbColor(255, 0, 255), // Magenta
]);

// References the list [colorPalette] was constructed with.
final colors = colorPalette.colors;

Modifying Palettes

For convenience, ColorPalette wraps some of List's methods for interfacing with its nested list of colors. You can add, addAll, and remove colors from the list, as well as use the insert, insertAll, getRange, setRange, removeRange, and replaceRange methods. You can also get and set colors by position with bracket operators. The combine method or the + operator can also be used to combine palettes.

// Create an empty palette.
final colorPalette = ColorPalette.empty();

// Add a pure red RGB color to the palette.
colorPalette.add(RgbColor(255, 0, 0));

// Remove the pure red RGB color from the palette.
colorPalette.remove(RgbColor(255, 0, 0));

// Add every color in the provided list.
colorPalette.addAll(<ColorModel>[
  RgbColor(0, 0, 0), // Black
  RgbColor(144, 144, 144), // Grey
  RgbColor(255, 255, 255), // White
  RgbColor(255, 0, 0), // red
  RgbColor(0, 255, 0), // green
  RgbColor(0, 0, 255), // blue
  RgbColor(255, 255, 0), // yellow
  RgbColor(0, 255, 255), // cyan
  RgbColor(255, 0, 255), // Magenta
]);

// [RgbColor(255, 255, 255), RgbColor(255, 0, 0)]
print(colorPalette.getRange(2, 4));

ColorPalette has two sorting methods, sortBy and sortByHue, that can be called to sort the color palette based on a variety of properties, as well as reverse which reverses the order of the colors in the palette.

// Sorts the colors in the palette from the highest
// perceived brightness value to the lowest.
colorPalette.sortBy(ColorSortingProperty.brightest);


// Sorts the colors in the palette from the lowest
// perceived brightness value to the highest.
colorPalette.sortBy(ColorSortingProperty.dimmest);

// Sorts the colors in the palette from the highest
// lightness value to the lowest.
colorPalette.sortBy(ColorSortingProperty.lightest);

// Sorts the colors in the palette from the lowest
// lightness value to the highest.
colorPalette.sortBy(ColorSortingProperty.darkest);

// Sorts the colors in the palette from the highest
// intensity value to the lowest.
colorPalette.sortBy(ColorSortingProperty.mostIntense);

// Sorts the colors in the palette from the lowest
// intensity value to the highest.
colorPalette.sortBy(ColorSortingProperty.leastIntense);

// Sorts the colors in the palette from the highest
// saturation value to the lowest.
colorPalette.sortBy(ColorSortingProperty.deepest);

// Sorts the colors in the palette from the lowest
// saturation value to the highest.
colorPalette.sortBy(ColorSortingProperty.dullest);

// Sorts the colors in the palette from the highest combined
// saturation and value values to the lowest.
colorPalette.sortBy(ColorSortingProperty.richest);

// Sorts the colors in the palette from the lowest combined
// saturation and value values to the highest.
colorPalette.sortBy(ColorSortingProperty.muted);

// Sorts the colors by their distance to a red hue. (0°)
colorPalette.sortBy(ColorSortingProperty.red);

// Sorts the colors by their distance to a red-orange hue. (30°)
colorPalette.sortBy(ColorSortingProperty.redOrange);

// Sorts the colors by their distance to a orange hue. (60°)
colorPalette.sortBy(ColorSortingProperty.orange);

// Sorts the colors by their distance to a yellow-orange hue. (90°)
colorPalette.sortBy(ColorSortingProperty.yellowOrange);

// Sorts the colors by their distance to a yellow hue. (120°)
colorPalette.sortBy(ColorSortingProperty.yellow);

// Sorts the colors by their distance to a yellow-green hue. (150°)
colorPalette.sortBy(ColorSortingProperty.yellowGreen);

// Sorts the colors by their distance to a green hue. (180°)
colorPalette.sortBy(ColorSortingProperty.green);

// Sorts the colors by their distance to a cyan hue. (210°)
colorPalette.sortBy(ColorSortingProperty.cyan);

// Sorts the colors by their distance to a blue hue. (240°)
colorPalette.sortBy(ColorSortingProperty.blue);

// Sorts the colors by their distance to a blue-violet hue. (270°)
colorPalette.sortBy(ColorSortingProperty.blueViolet);

// Sorts the colors by their distance to a violet hue. (300°)
colorPalette.sortBy(ColorSortingProperty.violet);

// Sorts the colors by their distance to a magenta hue. (330°)
colorPalette.sortBy(ColorSortingProperty.magenta);

The sortByHue method will sort the colors based on their position in the color wheel going in a single direction, clockwise or counter-clockwise.

// Sorts the colors in the palette, starting from 0° going in
// a clockwise direction around the wheel.
colorPalette.sortByHue();

// Sorts the colors in the palette, starting from 145° going in
// a counter-clockwise direction around the wheel.
colorPalette.sortByHue(startingFrom: 145, clockwise: false);

ColorPalette also wraps ColorModel's color adjustment methods: invert, opposite, rotateHue, warmer, and cooler, but applies the color adjustments to the whole palette.

// Invert every color in the palette.
colorPalette.invert();

// Set every color in the palette to their respective opposites.
colorPalette.opposite();

// Rotate the hues of every color in the palette by 15°.
colorPalette.rotateHue(15);

// Make every color in the palette 10% warmer.
colorPalette.warmer(10);

// Make every color in the palette 20% cooler.
colorPalette.cooler(20);

Color Getters

ColorPalette has a variety of getters for retrieving colors with a specific property:

/// Returns the color with the highest perceived brightness value.
ColorModel get brightest;

/// Returns the color with the lowest perceived brightness value.
ColorModel get dimmest;

/// Returns the color with the highest lightness value.
ColorModel get lightest;

/// Returns the color with the lowest lightness value.
ColorModel get darkest;

/// Returns the color with the highest intensity value.
ColorModel get mostIntense;

/// Returns the color with the lowest intensity value.
ColorModel get leastIntense;

/// Returns the color with the highest saturation value.
ColorModel get deepest;

/// Returns the color with the lowest saturation value.
ColorModel get dullest;

/// Returns the color with the highest combined saturation and value values.
ColorModel get richest;

/// Returns the color with the lowest combined saturation and value values.
ColorModel get muted;

/// Returns the color with the reddest hue. (0°)
ColorModel get red;

/// Returns the color with the most red-orange hue. (30°)
ColorModel get redOrange;

/// Returns the color with the orangest hue. (60°)
ColorModel get orange;

/// Returns the color with the most yellow-orange hue. (90°)
ColorModel get yellowOrange;

/// Returns the color with the yellowest hue. (120°)
ColorModel get yellow;

/// Returns the color with the most yellow-green hue. (150°)
ColorModel get yellowGreen;

/// Returns the color with the greenest hue. (180°)
ColorModel get green;

/// Returns the color with the most cyan hue. (210°)
ColorModel get cyan;

/// Returns the color with the most bluest hue. (240°)
ColorModel get blue;

/// Returns the color with the most blue-violet hue. (270°)
ColorModel get blueViolet;

/// Returns the color with the most violet hue. (300°)
ColorModel get violet;

/// Returns the color with the most magenta hue. (330°)
ColorModel get magenta;

Libraries

palette
A library for creating, generating, and interfacing with color palettes. With support for constructing colors in the CMYK, HSI, HSL, HSP, HSB, LAB, Oklab, RGB, and XYZ color spaces.