Naivete Precedes Misrepresentation
    Wondering what’s next for npm?Check out our public roadmap! »

    color-combos
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.12 • Public • Published

    Color Combos

    semantic-release Build Status npm version last release last commit

    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.

    Install

    npm i color-combos

    DownloadsWeekly Downloads

    20

    Version

    1.0.12

    License

    MIT

    Unpacked Size

    100 kB

    Total Files

    23

    Last publish

    Collaborators

    • avatar