{"id":12976,"library":"color-parse","title":"Color String Parser","description":"color-parse is a fast and compact JavaScript library designed for parsing a wide array of CSS-compatible color strings into a structured object representation. It supports numerous formats including color keywords (e.g., 'red'), hex codes (`#RGB`, `#RRGGBB`, with optional alpha), functional notations like `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`, `cmyk()`, and modern color spaces such as `xyz()`, `luv()`, `lab()`, `lch()`, `oklab()`, `oklch()`, and the generic `color()` function. Additionally, it can parse custom formats like `R:10 G:20 B:30` and array-like inputs. The library currently ships as version 2.0.2 and is actively maintained. It emphasizes performance and minimal bundle size, differentiating itself from alternatives by focusing solely on parsing without performing color space conversions, which helps keep its footprint small compared to libraries like `parse-color` or `color-string` that offer extensive conversion APIs.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/colorjs/color-parse","tags":["javascript","color","parse","color-parse","color-string","parse-color","css color","typescript"],"install":[{"cmd":"npm install color-parse","lang":"bash","label":"npm"},{"cmd":"yarn add color-parse","lang":"bash","label":"yarn"},{"cmd":"pnpm add color-parse","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports its main parsing function as a default export for ESM.","wrong":"import { parse } from 'color-parse';","symbol":"parse","correct":"import parse from 'color-parse';"},{"note":"CommonJS usage for Node.js environments. The function is the default export.","symbol":"parse","correct":"const parse = require('color-parse');"},{"note":"Importing the TypeScript type definition for the parsed color object.","symbol":"ParsedColor","correct":"import type { ParsedColor } from 'color-parse';"}],"quickstart":{"code":"import parse from 'color-parse';\n\n// Parsing various CSS color strings\nconst parsedRed = parse('red');\nconsole.log('Parsed Red:', parsedRed); // { space: 'rgb', values: [ 255, 0, 0 ], alpha: 1 }\n\nconst parsedHex = parse('#00FF00AA');\nconsole.log('Parsed Hex with Alpha:', parsedHex); // { space: 'rgb', values: [ 0, 255, 0 ], alpha: 0.6666666666666666 }\n\nconst parsedHSLA = parse('hsla(12 10% 50% / .3)');\nconsole.log('Parsed HSLA:', parsedHSLA); // { space: 'hsl', values: [ 12, 10, 50 ], alpha: 0.3 }\n\n// Example of a custom format\nconst parsedCustom = parse('R:10 G:20 B:30');\nconsole.log('Parsed Custom RGB:', parsedCustom); // { space: 'rgb', values: [ 10, 20, 30 ], alpha: 1 }\n\n// Example with `color()` function\nconst parsedColorFunc = parse('color(srgb 0.1 0.2 0.3 / 0.5)');\nconsole.log('Parsed color() function:', parsedColorFunc); // { space: 'srgb', values: [ 0.1, 0.2, 0.3 ], alpha: 0.5 }\n\n// Invalid input example\ntry {\n  parse('yellowblue');\n} catch (e) {\n  console.error('Error parsing invalid string:', e.message); // Will likely be 'Unable to parse color: yellowblue'\n}\n","lang":"typescript","description":"Demonstrates parsing various color formats including keywords, hex, HSLA, custom RGB, and the generic `color()` function, showing the structured output and error handling for unparseable strings."},"warnings":[{"fix":"Use a dedicated color conversion library in conjunction with `color-parse` for transformations.","message":"The library is a pure parser and does not perform any color space conversions. If you need to convert colors between spaces (e.g., RGB to HSL), you'll need an additional library like `color-space` or `color-rgba`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement client-side validation for color component ranges if strict adherence to CSS color specification limits is required.","message":"When parsing modern color spaces like `lab()`, `lch()`, `oklab()`, or `oklch()`, the library will parse the values, but it does not validate if these values fall within the W3C CSS Color Module Level 4 specified ranges for these color spaces. Developers should be aware of these limits (e.g., L from 0-100, a/b from -128 to 127) when providing input.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure all inputs to the `parse` function are valid color strings.","message":"The parser is designed for color strings and will throw an error if passed non-string inputs (e.g., objects, arrays, numbers).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement to `import parse from 'color-parse';`","cause":"Attempting to use named import syntax (`import { parse } from 'color-parse'`) for a default export in an ESM environment.","error":"TypeError: parse is not a function"},{"fix":"Review the input string to ensure it conforms to one of the supported CSS color formats or custom string patterns detailed in the documentation.","cause":"The input string does not match any of the supported color formats, or it contains syntax errors.","error":"Unable to parse color: [your_input_string]"},{"fix":"Always ensure the argument passed to `parse` is a valid string representation of a color.","cause":"A non-string value (e.g., `null`, `undefined`, `object`, `array`, `number`) was passed to the `parse` function.","error":"TypeError: [input] is not a function/string (or similar errors like 'split is not a function')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}