CSSType - Strict CSS Type Definitions

Common errors

• Type '"middle"' is not assignable to type '"-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | ...'.

  cause An invalid or unrecognized value was assigned to a CSS property type.
  fix Replace 'middle' with a valid CSS `text-align` value such as 'center', 'left', 'right', 'start', or 'end'.

• Property 'colour' does not exist on type 'Properties<string | number, string>'. Did you mean 'color'?

  cause A non-standard or misspelled CSS property name was used.
  fix Correct the property name to 'color', which is the standard CSS property for text color. CSSType follows the standard W3C and MDN property names.

• TS2742: The inferred type of '...' cannot be named without a reference to 'csstype/dist/csstype'. This is likely not portable. A type annotation is necessary.

  cause TypeScript might struggle to infer a complex type from `csstype` without an explicit `import type` statement or when using `require()` for types, especially in older TS versions or specific project configurations.
  fix Ensure you are using `import type * as CSS from 'csstype';` for all `csstype` imports to correctly reference type declarations without bundling runtime values. If the issue persists, explicitly annotate the type, e.g., `const style: CSS.Properties = { ... }`.

Warnings

• breaking CSSType v3 introduced significant breaking changes, primarily impacting how types are structured and accessed. The main `CSS` namespace now aggregates most types, requiring adjustments to existing type imports from previous versions (e.g., `v2`).
  Fix: Review the CSSType v3 migration guide on GitHub. Update import statements from specific sub-paths or direct exports to `import type * as CSS from 'csstype';` and then access types like `CSS.Properties` or `CSS.AtRule.Viewport`.
• gotcha Incorrect CSS property values will result in TypeScript errors (e.g., `textAlign: 'middle'`). CSSType enforces strict adherence to MDN-defined valid values.
  Fix: Consult MDN Web Docs for the correct and accepted values for the CSS property causing the error. Ensure all values conform to the formal CSS syntax.
• gotcha Choosing the correct type interface (e.g., `Properties`, `PropertiesHyphen`, `PropertiesFallback`) is crucial for various use cases like CSS-in-JS libraries or style objects that accept array fallbacks.
  Fix: Select the interface that matches your styling approach: `Properties` for camelCase JS objects, `PropertiesHyphen` for kebab-case (often for React `style` prop or styled-components), and `Fallback` variants if you need to allow array values for fallbacks.
• gotcha Using custom CSS properties (CSS Variables) with `csstype` might require type assertions or module augmentation, as they are not statically known by the library.
  Fix: For individual custom properties, use type assertions like `{'--my-var': '10px' as CSS.Property.Width}`. For widespread usage, consider TypeScript module augmentation to extend `Properties` or related interfaces with your custom properties.

Install

• npm install csstype npm
• yarn add csstype yarn
• pnpm add csstype pnpm

Imports

• CSS.Properties
  wrong:

  import * as CSS from 'csstype';

  correct:

  import type * as CSS from 'csstype';

  For TypeScript, use `import type` as `csstype` only provides type declarations and has no runtime value. Not using `type` could lead to unnecessary import statements in compiled JavaScript if your bundler doesn't tree-shake types effectively.
• CSS.PropertiesHyphen
  wrong:

  import { PropertiesHyphen } from 'csstype/dist/prop-types';

  correct:

  import type { PropertiesHyphen } from 'csstype';

  Specific interfaces like `PropertiesHyphen` are directly available as named exports from the main package entry point. Direct imports from internal paths like `dist/prop-types` are generally discouraged and might break in future versions.
• CSS.AtRule.FontFace
  wrong:

  import type { FontFace } from 'csstype/at-rules';

  correct:

  import type { AtRule } from 'csstype';

  At-rule types are nested under the `AtRule` namespace. Access them via `AtRule.FontFace` after importing `AtRule`. Direct module imports for nested types are not the standard pattern.

Quickstart

Demonstrates importing `csstype` types, defining an interface using CSS property types, and applying them within a styled object, highlighting type checking for property names and values.

import type * as CSS from 'csstype';

interface CustomTheme {
  primary: CSS.Property.Color;
  secondary: CSS.Property.Color;
}

// Example usage with a common CSS-in-JS pattern
const getButtonStyle = (theme: CustomTheme): CSS.Properties => ({
  backgroundColor: theme.primary,
  color: theme.secondary,
  padding: '8px 16px',
  borderRadius: '4px',
  border: '1px solid currentColor',
  ':hover': {
    opacity: 0.9,
    cursor: 'pointer'
  },
  // Type error: 'middle' is not a valid textAlign value
  textAlign: 'middle' as CSS.Property.TextAlign,
  // Type error: 'colour' is not a standard CSS property
  // @ts-ignore: Intentionally demonstrating a property error
  colour: 'red'
});

const myTheme: CustomTheme = {
  primary: '#007bff',
  secondary: 'white'
};

const buttonStyles = getButtonStyle(myTheme);

console.log(buttonStyles);