Have ideas to improve npm?Join in the discussion! »

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

    2.0.0 • Public • Published

    Colorizr

    NPM version npm bundle size build status Maintainability Test Coverage

    Color conversion, manipulation, comparison and analysis.

    Highlights

    • 🏖 Easy to use: Works with HSL and RGB, including CSS strings
    • ♿️ Acessibility: WCAG analysis and comparison.
    • 🛠 Small: Less than 4k (gzipped) and zero dependencies.
    • 🟦 Modern: Written in Typescript.

    Setup

    Install

    npm install --save colorizr

    Usage

    import { luminance } from 'colorizr';
     
    const lux = luminance('#ff0044'); // 0.2168

    Or you can create an instance to access all methods:

    import Colorizr from 'Colorizr';
     
    const colorizr = new Colorizr('#ff0044');

    Methods

    String inputs accept css values: hex, rgb(a), hsl(a) and named colors.

    brightnessDifference(left: string, right: string): number
    get the brightness difference between 2 colors

    import { brightnessDifference } from 'colorizr';
     
    brightnessDifference('#fff', 'rgb(255, 0, 68)'); // 171.003

    chroma(input: string): number
    get the chroma of a color

    import { chroma } from 'colorizr';
     
    chroma('#ff0044'); // 1
    chroma('#ffc0cb'); // 0.2471

    colorDifference(left: string, right: string): number
    get the color difference between 2 colors

    import { colorDifference } from 'colorizr';
     
    colorDifference('hsl(0, 0%, 100%)', '#f04'); // 442

    compare(left: string, right: string): Analysis
    get the WCAG analysis for two colors

    import { compare } from 'colorizr';
     
    compare('#ff0044', '#fff');
     
    {
      "brightnessDifference"171.003,
      "colorDifference"442,
      "compliant"1,
      "contrast"3.94,
      "largeAA"true,
      "largeAAA"false,
      "normalAA"false,
      "normalAAA"false,
    }

    contrast(left: string, right: string): number
    get the WCAG contrast ratio between 2 colors

    import { contrast } from 'colorizr';
     
    contrast('hsl(0, 0%, 100%)', 'rgb(255, 0, 68)'); // 3.94

    darken(input: string, amount = 10): string
    get a color with decreased lightness

    import { darken } from 'colorizr';
     
    darken('#ff0044', 10); // #cc0036

    desaturate(input: string, amount: number): string
    get a color with decreased saturation

    import { desaturate } from 'colorizr';
     
    desaturate('#ff0044', 10); // #f20d4a

    fade(input: string, amount: number = 10, output?: ColorTypes = 'rgb'): string
    get a transparent color

    import { fade } from 'colorizr';
     
    fade('hsl(344, 100, 50)', 10); // rgba(255, 0, 68, 0.9)
    fade('#ff0044', 50, 'hsl'); // hsla(344, 100%, 50%, 0.5)

    formatCSS(input: HSL | RGB, options?: FormatOptions): string
    get the css string for a color model object

    import { formatCSS } from 'colorizr';
     
    formatCSS({ h: 344, s: 100, l: 50 }, { model: 'rgb' }); // 'rgb(255, 0, 68)'
    formatCSS({ r: 255, g: 0, b: 68 }, { alpha: 0.5, model: 'hsl' }); // 'hsla(344, 100%, 50%, 0.5)'

    formatHex(input: string): string
    format a short hex string 3 (or 4) digits into a 6 (or 8) digits.

    import { formatHex } from 'colorizr';
     
    formatHex('#07e'); // '#0077ee'
    formatHex('#f058'); // '#ff005588'

    hex2hsl(input: string): HSL
    convert a hex string into a HSL object

    import { hex2hsl } from 'colorizr';
     
    hex2hsl('#ff0044'); // { h: 344, s: 100, l: 50 }

    hex2rgb(input: string): RGB
    convert a hex string into a RGB object

    import { hex2rgb } from 'colorizr';
     
    hex2rgb('#ff0044'); // { r: 255, g: 0, b: 68 }

    hsl2hex(input: HSL): string
    convert a HSL object into a hex string

    import { hsl2hex } from 'colorizr';
     
    hsl2hex({ h: 344, s: 100, l: 50 }); // '#ff0044'

    hsl2rgb(input: HSL): RGB
    convert a HSL object into a RGB object

    import { hsl2rgb } from 'colorizr';
     
    hsl2rgb({ h: 344, s: 100, l: 50 }); // { r: 255, g: 0, b: 68 }

    isValidColor(input: any): boolean
    check if the input can be parsed correctly

    import { isValidColor } from 'colorizr';
     
    isValidColor('#f04'); // true
    isValidColor('#ff0044'); // true
    isValidColor('#ff004400'); // true
    isValidColor('rgb(100, 255, 0)'); // true
    isValidColor('hsla(344, 100%, 50%)'); // true
    isValidColor('blue'); // true
    isValidColor('aliceblue'); // true
    isValidColor('#mmff00'); // false
    isValidColor('blue-ish'); // false

    isValidHex(input: any): boolean
    check if the input is a valid hex

    import { isValidHex } from 'colorizr';
     
    isValidHex('#f04'); // true

    lighten(input: string, amount: number): string
    get a color with increased lightness

    import { lighten } from 'colorizr';
     
    lighten('#ff0044', 10); // #ff3369

    luminance(input: string): number
    get the relative brightness according to the WCAG definition. Normalized to 0 for black and 1 for white.

    import { luminance } from 'colorizr';
     
    luminance('#ff0044'); // 0.2168

    name(input: string): string
    get the named color. return the hex code if it can't be named

    import { name } from 'colorizr';
     
    name('#ffc0cb', 10); // pink
    name('rgb(176, 224, 230)'); // 'powderblue'
    name('hsl(344, 100, 50)'); // #ff0044

    palette(input: string, options?: PaletteOptions): string[]
    get a palette for a color

    import { palette } from 'colorizr';
     
    palette('#ff0044');
    // ['#ff0044', '#ff7700', '#88ff00', '#00ff77', '#0088ff', '#7700ff'];
     
    palette('#ff0044', { type: 'monochromatic' });
    // ['#ff99b4', '#ff5582', '#ff1150', '#cc0036', '#880024', '#440012']

    parseCSS(input: string, output: ColorTypes = 'hex'): string | HSL | RGB
    parse a css string to hex, hsl or rgb

    import { parseCSS } from 'colorizr';
     
    parseCSS('hsl(270 60% 70%)'); // '#b385e0'
    parseCSS('#ff0044', 'hsl'); // { h: 344, l: 50, s: 100 }

    random(): string
    get a random color

    import { random } from 'colorizr';
     
    random(); // '#b385e0'

    rgb2hex(input: RGB | RGBArray): string
    convert a RGB object into a hex string

    import { rgb2hex } from 'colorizr';
     
    rgb2hex({ r: 255, g: 55, b: 75 }); // '#ff374b'
    rgb2hex([255, 0, 68]); // '#ff0044'

    rgb2hsl(input: RGB | RGBArray): HSL
    convert a RGB object into a HSL object

    import { rgb2hsl } from 'colorizr';
     
    rgb2hsl({ r: 255, g: 55, b: 75 }); // { h: 354, s: 100, l: 60.78 }
    rgb2hsl([255, 0, 68]); // { h: 344, s: 100, l: 50 }

    rotate(input: string, degrees = 15): string get a color with changed hue

    import { rotate } from 'colorizr';
     
    rotate('#ff0044', 30); // #ff3b00

    saturate(input: string, amount: number): string
    get a color with increased saturation

    import { saturate } from 'colorizr';
     
    saturate('#ff0044', 10); // #ff0044 (alreay at the maximum)
    saturate('pink', 10); // #ffc0cb

    scheme(input: string, type: Scheme): string[]
    get the scheme for a color

    import { scheme } from 'colorizr';
     
    const complementary = scheme('rgb(255, 0, 68)'); // ['#ff0044', '#00ffbb']
    const triadic = scheme('#ff0044', 'triadic'); // ['#ff0044', '#44ff00', '#0044ff']

    textColor(input: string): string
    get a constrasted color to use with text

    import { textColor } from 'colorizr';
     
    textColor('#ff0044'); // #ffffff
    textColor('#fff800'); // #000000

    Instance API

    import Colorizr from 'Colorizr';
     
    const colorizr = new Colorizr('#ff0044');
     
    colorizr.hex; // #ff0044
    colorizr.hsl; // { h: 344, s: 100, l: 50 };
    colorizr.rgb; // { r: 255, g: 0, b: 68 };

    Getters

    colorizr.hex
    returns the hex

    colorizr.hsl
    returns the hsl object

    colorizr.rgb
    returns the rgb object

    colorizr.hue
    returns the color hue, between 0 and 360

    colorizr.saturation
    returns the color saturation, between 0 and 100

    colorizr.lightness
    returns the color lightness, between 0 and 100

    colorizr.red
    returns the color red level, between 0 and 255

    colorizr.green
    returns the color green level, between 0 and 255

    colorizr.blue
    returns the color blue level, between 0 and 255

    colorizr.luminance

    colorizr.chroma

    colorizr.textColor

    Manipulation

    colorizr.lighten(percentage = 10)

    colorizr.darken(percentage = 10)

    colorizr.saturate(percentage = 10)

    colorizr.saturate(percentage = 10)

    colorizr.rotate(degrees = 15)

    colorizr.invert()

    colorizr.fade(percentage = 10)

    Comparison

    colorizr.compare(color: string)
    returns an object with the analysis (check the compare output above)

    References

    calculating-color-contrast
    Colour Contrast Check
    Contrast Checker
    Converting Color Spaces in typescript

    Install

    npm i colorizr

    DownloadsWeekly Downloads

    102

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    247 kB

    Total Files

    248

    Last publish

    Collaborators

    • avatar