color-combos
v1.1.0
Published
Get accessibility information about colour combinations
Downloads
42,091
Readme
Color Combos
For each color passed, ColorCombos
will calculate the color contrast ratio and accessibility rating between itself and every other color that was supplied. ColorCombos
returns an array of colors, and for each color, combinations of other colors passed along with the contrast ratio and accessibility rating.
By default it will return the full details of the colors, but it can set to return only compact details, only unique colors and / or only colors that meet a certain threshold.
The default shape of the returned array can be expressed as:
[
{
color?: number[];
hex: string;
model?: string;
valpha?: number;
combinations: [
{
color?: number[];
contrast: number;
hex: string;
model?: string;
valpha?: number;
accessibility: {
aa: boolean;
aaLarge: boolean;
aaa: boolean;
aaaLarge: boolean;
};
}
];
}
];
Installation
import ColorCombos from 'color-combos';
Usage
ColorCombos
takes two arguments; colors: string[] | { [name: string]: string }
and optional options: { compact?: boolean; threshold?: number; uniq?: boolean; }
ColorCombos(
colors: string[] | { [name: string]: string },
options?: {
compact?: boolean;
threshold?: number;
uniq?: boolean;
}
)
colors: string[] | { [name: string]: string }
The colors argument will accept either an array of colors as strings, or an object of colors where the values are strings.
Array
ColorCombos(['#fff', '#000']);
Object
ColorCombos({
white: '#fff',
black: '#000',
});
Both of these examples return an array of colors and their combinations as:
[
{
"color": [255, 255, 255],
"combinations": [
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"color": [0, 0, 0],
"contrast": 21,
"hex": "#000000",
"model": "rgb",
"valpha": 0.5
}
],
"hex": "#FFFFFF",
"model": "rgb",
"valpha": 0.5
},
{
"color": [0, 0, 0],
"combinations": [
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"color": [255, 255, 255],
"contrast": 21,
"hex": "#FFFFFF",
"model": "rgb",
"valpha": 0.5
}
],
"hex": "#000000",
"model": "rgb",
"valpha": 0.5
}
]
Color strings are supported in a number of formats
Supported color formats
- Named:
white
- Hex:
#fff
- RGB:
rgb(255, 255, 255)
Passing more than two colors
Passing more than two colors will result in the returned array and combinations increasing in size.
ColorCombos(['#fff', '#ccc', '#000']);
returns
[
{
"color": [255, 255, 255],
"combinations": [
{
"accessibility": { "aa": false, "aaLarge": false, "aaa": false, "aaaLarge": false },
"color": [204, 204, 204],
"contrast": 1.6059285649300714,
"hex": "#CCCCCC",
"model": "rgb",
"valpha": 1
},
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"color": [0, 0, 0],
"contrast": 21,
"hex": "#000000",
"model": "rgb",
"valpha": 1
}
],
"hex": "#FFFFFF",
"model": "rgb",
"valpha": 1
},
{
"color": [204, 204, 204],
"combinations": [
{
"accessibility": { "aa": false, "aaLarge": false, "aaa": false, "aaaLarge": false },
"color": [255, 255, 255],
"contrast": 1.6059285649300714,
"hex": "#FFFFFF",
"model": "rgb",
"valpha": 1
},
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"color": [0, 0, 0],
"contrast": 13.076546777106755,
"hex": "#000000",
"model": "rgb",
"valpha": 1
}
],
"hex": "#CCCCCC",
"model": "rgb",
"valpha": 1
},
{
"color": [0, 0, 0],
"combinations": [
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"color": [255, 255, 255],
"contrast": 21,
"hex": "#FFFFFF",
"model": "rgb",
"valpha": 1
},
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"color": [204, 204, 204],
"contrast": 13.076546777106755,
"hex": "#CCCCCC",
"model": "rgb",
"valpha": 1
}
],
"hex": "#000000",
"model": "rgb",
"valpha": 1
}
]
Optional options: { compact?: boolean; threshold?: number; uniq?: boolean; }
ColorCombos
can take some optional options that can affect the returned array of colors. Options are represented as an object that can have three keys; compact
, threshold
, and uniq
. By default those options are set to:
{
"compact": false,
"threshold": 0,
"uniq": true
}
compact: boolean
If all you're after is the accessibility information for each color combination you can set compact
to true and ColorCombos
will omit non-essential information about each color.
ColorCombos(['#fff', '#ccc', '#000'], { compact: true });
returns
[
{
"combinations": [
{
"accessibility": { "aa": false, "aaLarge": false, "aaa": false, "aaaLarge": false },
"contrast": 1.6059285649300714,
"hex": "#CCCCCC"
},
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"contrast": 21,
"hex": "#000000"
}
],
"hex": "#FFFFFF"
},
{
"combinations": [
{
"accessibility": { "aa": false, "aaLarge": false, "aaa": false, "aaaLarge": false },
"contrast": 1.6059285649300714,
"hex": "#FFFFFF"
},
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"contrast": 13.076546777106755,
"hex": "#000000"
}
],
"hex": "#CCCCCC"
},
{
"combinations": [
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"contrast": 21,
"hex": "#FFFFFF"
},
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"contrast": 13.076546777106755,
"hex": "#CCCCCC"
}
],
"hex": "#000000"
}
]
threshold: number
If you would like to omit color combinations that do not meet a certain color contrast ratio, you can set a contrast ratio threshold
and ColorCombos
will omit colors that do not meet it.
ColorCombos(['#fff', '#ccc', '#000'], { compact: true, threshold: 3 });
This will omit color combinations that do not meet at least a color contrast ratio of 3:1 and returns:
[
{
"combinations": [
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"contrast": 21,
"hex": "#000000"
}
],
"hex": "#FFFFFF"
},
{
"combinations": [
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"contrast": 13.076546777106755,
"hex": "#000000"
}
],
"hex": "#CCCCCC"
},
{
"combinations": [
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"contrast": 21,
"hex": "#FFFFFF"
},
{
"accessibility": { "aa": true, "aaLarge": true, "aaa": true, "aaaLarge": true },
"contrast": 13.076546777106755,
"hex": "#CCCCCC"
}
],
"hex": "#000000"
}
]
uniq: boolean
By default, ColorCombos
will only return uniq colors from the supplied arguments. If you would like it to not omit duplicates, set the uniq
option to false
ColorCombos(['#fff', 'rgb(255,255,255)', '#000'], { compact: true, uniq: false });
Even though #fff
and rgb(255,255,255)
are the same color, ColorCombos
will not omit the duplicate from the returned results.