Parse CSS Box-Shadow Values to JavaScript Objects

css-box-shadow-parser Features

• Multi-layer parsing - splits comma-separated shadows into one object per layer.
• Full declaration support - accepts raw values or complete box-shadow: ...; declarations and strips the property name and semicolon automatically.
• All color formats - 3/4/6/8-digit hex, rgb(), rgba(), hsl(), hsla(), named colors, transparent, and currentcolor.
• Modern and legacy syntax - handles both comma syntax and the space/slash syntax such as rgb(0 0 0 / 0.5) and hsl(270 80% 50% / 0.6).
• Smart comma splitting - commas inside color functions are never mistaken for layer separators.
• Resolved hex + alpha - every layer returns a normalized 6-digit hex plus a separate alpha value from 0 to 1.
• Inset detection - recognizes the inset keyword wherever it appears in the value.
• Negative offsets and spread - parses negative x, y, and spread values correctly.
• Graceful handling - CSS-wide keywords like none, initial, and inherit return an empty array.
• Zero dependencies - small UMD bundle that works in the browser and Node.js.

Pick a shadow type from the dropdown to see it parsed in real time. The selected CSS box-shadow value is passed to parse() and the resulting layer objects are shown below, along with a live preview box.

Parsed output:

[
  {
    "inset": false,
    "x": 4,
    "y": 4,
    "blur": 10,
    "spread": 0,
    "color": "rgba(0,0,0,0.4)",
    "alpha": 0.4,
    "hex": "#000000"
  }
]

Got the parsed objects? Click Back to CSS to run them through stringify() - the inverse of parse() - and rebuild a valid box-shadow string. This is the full round-trip: read a shadow, edit the values, and write it straight back to CSS.

box-shadow: 4px 4px 10px rgba(0,0,0,0.4);

How css-box-shadow-parser compares with common alternatives.

Install the package from npm for use in Node.js or any bundler, or drop in the script from a CDN to use it directly in the browser with no build step.

Direct download

Browse the source code on GitHub or grab the package from npm.

GitHub npm Download JavaScript Code

NPM

Command

npm install css-box-shadow-parser

Node.js Usage

JavaScript

// CommonJS
// const { parse, parseSingle, split, stringify } = require('css-box-shadow-parser');

// ES module (if your build supports it)
import { parse, parseSingle, split, stringify } from 'css-box-shadow-parser';

// Single layer
parse('4px 4px 10px rgba(0,0,0,0.4)');

// Multi-layer
parse('0 1px 2px #0002, 0 4px 8px #0002');

// Full CSS declaration - strips "box-shadow:" and ";" automatically
parse('box-shadow: inset 0 2px 4px rgba(0,0,0,.24);');

// CSS keyword - returns empty array
parse('none'); // []

---

Browser Usage

HTML

<script src="https://unpkg.com/css-box-shadow-parser"></script>

<script>
const { parse, parseSingle, split, stringify } = BoxShadowParser;

const layers = parse('4px 4px 10px rgba(0,0,0,0.4)');
console.log(layers);

// output
// [{"inset":false,"x":4,"y":4,"blur":10,"spread":0,"color":"rgba(0,0,0,0.4)","alpha":0.4,"hex":"#000000"}]

// Edit
layers[0].blur = 20;
const css = stringify(layers);
// 4px 4px 20px rgba(0,0,0,0.4);
</script>

Try it yourself

Parse a shadow value into an array of layer objects:

Parse

JavaScript

const layers = BoxShadowParser.parse('4px 4px 10px rgba(0,0,0,0.4)');

console.log(layers[0]);
// {
//   inset: false,
//   x: 4,
//   y: 4,
//   blur: 10,
//   spread: 0,
//   color: 'rgba(0,0,0,0.4)',
//   alpha: 0.4,
//   hex: '#000000'
// }

---

Multi-layer shadows

JavaScript

const layers = BoxShadowParser.parse(
  '0 1px 2px rgba(0,0,0,.07), 0 4px 8px rgba(0,0,0,.07), 0 12px 24px rgba(0,0,0,.07)'
);
// returns 3 layer objects

---

Full CSS declaration

JavaScript

BoxShadowParser.parse('box-shadow: inset 0 2px 4px rgba(0,0,0,.2);');
// works — property name and semicolon are stripped

---

Stringify back to CSS

JavaScript

const css = BoxShadowParser.stringify(layers);
// "0 1px 2px rgba(0,0,0,.07), 0 4px 8px rgba(0,0,0,.07), 0 12px 24px rgba(0,0,0,.07)"

document.querySelector('.card').style.boxShadow = css;

---

Edit and round-trip

JavaScript

const layers = BoxShadowParser.parse('0 4px 12px rgba(0,0,0,.3)');
layers[0].blur = 20;
layers[0].y = 8;
element.style.boxShadow = BoxShadowParser.stringify(layers);

Each parsed layer is a plain object with the following shape. Offsets, blur, and spread are returned as numbers, color keeps the original token, and hex plus alpha give you a normalized color you can use anywhere.

The library exposes three functions: parse() for full values, parseSingle() for one shadow token, and split() for tokenizing without parsing.

parse(shadow) - BoxShadowLayer[]

Parses a full box-shadow value, single or multi-layer. Accepts raw values or complete CSS declarations including the box-shadow: property name and trailing semicolon.

JavaScript

const { parse, parseSingle, split, stringify } = BoxShadowParser;

// parse() - always returns an ARRAY of shadow layers
const singleShadow = parse('0 2px 8px rgba(0,0,0,0.3)');
const insetShadow  = parse('box-shadow: inset 0 2px 4px rgba(0,0,0,.24);');
const multiShadow  = parse('0 1px 2px #0002, 0 4px 8px #0002'); // multi-layer
const noShadow     = parse('none'); // -> []

console.log(singleShadow);
console.log(insetShadow);
console.log(multiShadow);
console.log(noShadow);

Try it yourself

---

parseSingle(token) - BoxShadowLayer | null

Parses a single shadow token. Returns null for invalid or empty input.

JavaScript

const { parseSingle } = BoxShadowParser;

// parseSingle() - returns ONE layer object, or null for invalid input
const shadow     = parseSingle('6px 6px 0 #1a1a2e');
const insetLayer = parseSingle('inset 0 2px 4px coral');
const invalid    = parseSingle('not a shadow'); // -> null

console.log(shadow);
console.log(insetLayer);
console.log(invalid);

Try it yourself

---

split(shadow) - string[]

Splits a compound value on top-level commas without parsing. Commas inside rgba(), hsl() and other functions are correctly ignored.

JavaScript

const { split } = BoxShadowParser;

// split() - separates layers at top-level commas, WITHOUT parsing
const tokens = split('4px 4px 0 red, inset 0 0 10px rgba(0,0,0,.5)');
console.log(tokens);
// ['4px 4px 0 red', 'inset 0 0 10px rgba(0,0,0,.5)']

// commas inside rgba() / hsl() are correctly ignored
const safeSplit = split('0 2px 4px rgba(0,0,0,.5), 0 4px 8px hsl(270 80% 50%)');
console.log(safeSplit);
// ['0 2px 4px rgba(0,0,0,.5)', '0 4px 8px hsl(270 80% 50%)']

Try it yourself

---

stringify()

The inverse of parse(). Pass a single layer object or an array of layers and get back a valid CSS box-shadow string. Together, parse() and stringify() let you read a shadow, modify it in code, and write it straight back to CSS.

stringify(input) - string

Accepts a BoxShadowLayer object or an array of them. Numeric offsets are written with px (a value of 0 stays unitless), blur and spread are omitted when not needed, and the original color token is preserved when present - otherwise a color is rebuilt from hex and alpha.

JavaScript

const { parse, stringify } = BoxShadowParser;

// stringify() - turns layer objects back into a CSS box-shadow string
const layers = parse('6px 6px 12px #b8b9be, -6px -6px 12px #ffffff');
layers[0].blur = 24;                  // edit a value in code
console.log(stringify(layers));
// "6px 6px 24px #b8b9be, -6px -6px 12px #ffffff"

// build a shadow from a plain object
const css = stringify({ x: 0, y: 8, blur: 24, spread: 0, hex: '#6c63ff', alpha: 0.4 });
console.log(css);
// "0 8px 24px rgba(108, 99, 255, 0.4)"

// Single object also works
stringify({ inset: true, x: 2, y: 2, blur: 4, spread: 0, color: 'red' });
// "inset 2px 2px 4px red"

Try it yourself

---

The package ships with built-in TypeScript definitions (index.d.ts), so you get full autocomplete and type checking with no @types install required.

import { parse, stringify, BoxShadowLayer } from 'css-box-shadow-parser';

const layers: BoxShadowLayer[] = parse('0 8px 24px rgba(0,0,0,0.4)');

const first: BoxShadowLayer = layers[0];
first.blur;   // number
first.hex;    // string
first.inset;  // boolean

const css: string = stringify(layers);

The exported BoxShadowLayer interface describes every field returned by parse() and parseSingle().

The examples below show the parsed output for common shadow patterns, from named colors and hex with alpha to inset and multi-layer shadows.

Named color

JavaScript

parse('0 0 28px 6px rebeccapurple')
// [{
//   inset: false, x: 0, y: 0, blur: 28, spread: 6,
//   color: 'rebeccapurple', alpha: 1, hex: '#663399'
// }]

---

8-digit hex with alpha

JavaScript

parse('0 8px 24px #00000066')
// [{
//   inset: false, x: 0, y: 8, blur: 24, spread: 0,
//   color: '#00000066', alpha: 0.4, hex: '#000000'
// }]

---

HSL color

JavaScript

parse('0 6px 20px hsl(270 80% 50% / 0.6)')
// [{
//   inset: false, x: 0, y: 6, blur: 20, spread: 0,
//   color: 'hsl(270 80% 50% / 0.6)', alpha: 0.6, hex: '#8019e6'
// }]

---

Inset shadow

JavaScript

parse('inset 0 2px 4px rgba(0,0,0,0.24)')
// [{
//   inset: true, x: 0, y: 2, blur: 4, spread: 0,
//   color: 'rgba(0,0,0,0.24)', alpha: 0.24, hex: '#000000'
// }]

---

Multi-layer (neumorphic)

JavaScript

parse('6px 6px 12px #b8b9be, -6px -6px 12px #ffffff')
// [
//   { inset: false, x:  6, y:  6, blur: 12, spread: 0, color: '#b8b9be', alpha: 1, hex: '#b8b9be' },
//   { inset: false, x: -6, y: -6, blur: 12, spread: 0, color: '#ffffff', alpha: 1, hex: '#ffffff' }
// ]

---

Split without parsing

JavaScript

split('4px 4px 0 red, inset 0 0 10px rgba(0,0,0,.5)')
// ['4px 4px 0 red', 'inset 0 0 10px rgba(0,0,0,.5)']

Every color format allowed in a CSS box-shadow is recognized and resolved to a hex value with a separate alpha channel.

Anywhere you need to read, edit, or transform shadows programmatically:

• Shadow editors and generators - parse a pasted value into sliders and color pickers, then stringify() the result back to CSS.
• Design-token and theme tools - convert shadow declarations into JSON tokens for design systems.
• CSS-to-JS pipelines - feed shadow data into canvas, SVG, or React Native styling, which use separate shadow properties.
• Linters and visual diff tools - compare two shadows layer by layer instead of as raw strings.
• Color extraction - pull resolved hex and alpha values out of any shadow for previews or contrast checks.
• Migration scripts - normalize inconsistent shadow syntax across a large codebase.

The library is plain ES5-compatible JavaScript in a UMD wrapper, so it runs anywhere with no build step.

Released under the MIT License - free to use in personal and commercial projects. See the LICENSE file on GitHub for full terms.

Related links