{"id":10701,"library":"csx","title":"CSX CSS Utilities for TypeStyle","description":"CSX (CSS eXpressions) is a utility library designed to simplify the creation of strongly typed CSS values and functions within TypeScript environments, primarily serving as a companion to the TypeStyle library. It offers a comprehensive set of helpers for common CSS properties and units, such as `color`, `rgb`, `hsl`, `px`, `em`, `percent`, as well as shorthand properties like `margin` and `padding`. The current stable version, 10.0.2, reflects ongoing development with a recent focus on aligning its output more closely with the CSS Object Model (CSSOM) for improved consistency and testability across different browsers and testing setups. This includes changes to color function spacing and the addition of optional alpha parameters for `rgb()` and `hsl()`. CSX maintains an active release cadence, delivering continuous enhancements and bug fixes. Its core differentiator lies in providing a robust, type-safe API for dynamic CSS value generation, significantly reducing runtime errors and improving code maintainability compared to raw string concatenation or less-typed approaches.","status":"active","version":"10.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/typestyle/csx","tags":["javascript","TypeScript","JSX","TSX","Layout","typescript"],"install":[{"cmd":"npm install csx","lang":"bash","label":"npm"},{"cmd":"yarn add csx","lang":"bash","label":"yarn"},{"cmd":"pnpm add csx","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CSX is primarily designed for TypeScript and ES module environments. CommonJS `require()` is not officially supported and may lead to issues with type inference or bundling in modern projects.","wrong":"const color = require('csx').color;","symbol":"color","correct":"import { color } from 'csx'"},{"note":"Named exports are the standard for all utility functions. Direct imports from subpaths are discouraged and may break with future updates.","wrong":"import rgb from 'csx/lib/rgb'","symbol":"rgb","correct":"import { rgb } from 'csx'"},{"note":"All core utilities should be imported directly from the top-level 'csx' package. Importing from internal paths ('dist', 'lib') is unstable and not recommended.","wrong":"import { px } from 'csx/dist/units'","symbol":"px","correct":"import { px } from 'csx'"},{"note":"While `import * as csx` works, it's generally better practice to destructure specific utilities for tree-shaking and clarity, especially with many functions available.","wrong":"import * as csx from 'csx'; const m = csx.margin;","symbol":"margin","correct":"import { margin } from 'csx'"}],"quickstart":{"code":"import { color, rgb, hsl, px, em, rem, percent, viewHeight, viewWidth, margin, padding, url, quote } from 'csx';\nimport { style } from 'typestyle'; // Assuming TypeStyle is used as recommended\n\n// Define some CSS values using CSX helpers\nconst brandColor = color('#1E90FF'); // Dodger Blue\nconst semiTransparent = rgb(30, 144, 255, 0.7); // RGB with alpha\nconst lightAccent = hsl(200, 80, 95); // HSL color\n\n// Unit helpers\nconst defaultPadding = px(16);\nconst headingFontSize = em(2.5);\nconst bodyFontSize = rem(1.1);\nconst viewportWidth = viewWidth(100);\nconst elementHeight = viewHeight(50);\nconst responsiveWidth = percent(75);\n\n// Shorthand properties\nconst cardMargin = margin(px(20), 'auto'); // Top/Bottom 20px, Left/Right auto\nconst elementPadding = padding(defaultPadding, px(10)); // Top/Bottom 16px, Left/Right 10px\n\n// URL and quoting helpers\nconst backgroundImage = url('/assets/background.jpg');\nconst fontFaceName = quote('My Custom Font');\n\n// Example of integrating with TypeStyle\nconst myStyledElement = style({\n  color: brandColor.toString(),\n  backgroundColor: semiTransparent.toString(),\n  border: `${px(1)} solid ${lightAccent.toString()}`,\n  padding: elementPadding.toString(),\n  margin: cardMargin.toString(),\n  width: responsiveWidth.toString(),\n  height: elementHeight.toString(),\n  fontSize: bodyFontSize.toString(),\n  fontFamily: fontFaceName.toString(),\n  backgroundImage: backgroundImage.toString(),\n  $nest: {\n    '& > h1': {\n      fontSize: headingFontSize.toString(),\n      textAlign: 'center',\n    },\n    '@media (max-width: 768px)': {\n      width: viewportWidth.toString(),\n      margin: margin(px(10)),\n    },\n  },\n});\n\nconsole.log('CSX Brand Color:', brandColor.toString());\nconsole.log('CSX Element Padding:', elementPadding.toString());\nconsole.log('CSX Card Margin:', cardMargin.toString());\nconsole.log('CSX Background Image:', backgroundImage.toString());\nconsole.log('CSX Font Face Name:', fontFaceName.toString());\nconsole.log('Generated TypeStyle class name:', myStyledElement);\n","lang":"typescript","description":"Demonstrates defining various CSS values and shorthands using CSX helpers like colors, units, margins, and then integrating them into a TypeStyle stylesheet."},"warnings":[{"fix":"Update any snapshot tests or assertions that directly compare the string output of CSX color functions. No code change is typically required for runtime behavior unless specific string comparisons are in place.","message":"CSS color functions (e.g., `rgb()`, `hsl()`) now include spaces after commas in their output to match the CSS Object Model (CSSOM). This changes the exact string output of color functions.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Verify `background-size` usage. If you were implicitly relying on incorrect output, ensure your code now explicitly passes position and size, e.g., `backgroundSize('center', '50%')` to get `'center / 50%'`.","message":"The behavior of `background-size` helper was fixed in `v9.0.2` to correctly use `/` between position and size. Code relying on the incorrect pre-`v9.0.2` output will produce different CSS.","severity":"breaking","affected_versions":">=9.0.2"},{"fix":"Ensure that when providing a `size` argument to `backgroundSize()`, a valid `position` argument (even if 'initial' or '0 0') is also provided to satisfy the type definition.","message":"In `v9.0.2`, a more specific type definition was added for `background-size` that throws a type error if `size` is provided but `position` is undefined. This improves type safety but can break existing code that was implicitly passing `undefined` for position.","severity":"gotcha","affected_versions":">=9.0.2"},{"fix":"Ensure that CSX is used alongside TypeStyle, as it's designed to complement its functionality. If you need vendor prefixing control, manage it via TypeStyle's configuration.","message":"Starting with `v5.0.0`, all styles generated by CSX are vendor prefixed by default and are explicitly meant to be used in conjunction with TypeStyle. Using CSX independently of TypeStyle or in other styling solutions may lead to unexpected behavior or incomplete CSS output.","severity":"breaking","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"This is an intended breaking change in output formatting. Adjust any tests or code that performs exact string comparisons on color function outputs to reflect the new spaced format. No functional code change is needed.","cause":"Difference in color function string output due to new spacing introduced in v10.0.0 to align with CSSOM.","error":"Expected `rgb(0, 0, 0)` but got `rgb(0,0,0)` in CSS output."},{"fix":"Always use the appropriate CSX helper functions for units and values, e.g., `px(10)` instead of `'10px'`, or `percent(50)` instead of `'50%'`. Ensure types match the function signatures.","cause":"Attempting to pass a raw string where a `csx` unit helper (like `px()`, `em()`) is expected, or providing an invalid value type to a CSX function.","error":"Type error: Argument of type 'string' is not assignable to parameter of type 'CssLength'."},{"fix":"Update your import statements to use ES module syntax: `import { color } from 'csx';`. Ensure your project's `tsconfig.json` (if applicable) and build setup are configured for ES modules (e.g., `\"module\": \"esnext\"` or `\"nodenext\"`).","cause":"Attempting to import `csx` using CommonJS `require()` syntax in an environment (e.g., a modern TypeScript project, browser ES module context, or Node.js with type:\"module\") that expects ES module syntax.","error":"ReferenceError: require is not defined"}],"ecosystem":"npm"}