csstype

What is csstype?

The csstype package provides TypeScript and Flow definitions for CSS properties and values. It is designed to enhance type safety and autocompletion when working with CSS in JavaScript and TypeScript projects. It includes types for CSS properties, pseudo-classes, pseudo-elements, and at-rules.

What are csstype's main functionalities?

Type definitions for CSS properties

Csstype allows developers to define CSS properties in an object with type checking. This ensures that the values assigned to CSS properties are valid according to the CSS specification.

{"color": "blue", "fontSize": "12px"}

Type definitions for pseudo-classes and pseudo-elements

Developers can use csstype to define styles for pseudo-classes and pseudo-elements with type safety, ensuring that the pseudo selectors and their associated styles are correctly typed.

{"::before": {"content": "'Before content'"}, ":hover": {"color": "red"}}

Type definitions for at-rules

Csstype includes type definitions for CSS at-rules like @media, allowing developers to write media queries with type-checked properties and values.

{"@media (min-width: 768px)": {"body": {"backgroundColor": "lightblue"}}}

Other packages similar to csstype

styled-components

Styled-components is a library for styling React components using tagged template literals. It provides a similar level of type safety and autocompletion when used with TypeScript, but it also includes runtime styling capabilities, which csstype does not.

emotion

Emotion is another CSS-in-JS library that allows for styling applications using JavaScript. It offers a similar developer experience to styled-components and can be used with TypeScript for type safety. Emotion also supports dynamic styling, which is not a feature of csstype.

typestyle

Typestyle is a TypeScript-friendly library that allows for writing type-safe CSS with JavaScript. It is similar to csstype in providing type definitions for CSS properties, but it also includes utilities for generating CSS classes and handling them in JavaScript.

README

CSSType

TypeScript and Flow definitions for CSS, generated by data from MDN. It provides autocompletion and type checking for CSS properties and values.

import * as CSS from 'csstype';

const style: CSS.Properties = {
  colour: 'white', // Type error on property
  textAlign: 'middle', // Type error on value
};

Getting started

$ npm install csstype
$ # or
$ yarn add csstype

Table of content

• Style types
• At-rule types
• Pseudo types
• Usage
• What should I do when I get type errors?
• Version 2.0
• Contributing
  • Commands

Style types

Properties are categorized in different uses and in several technical variations to provide typings that suits as many as possible.

All interfaces has one optional generic argument to define length. It defaults to string | 0 because 0 is the only length where the unit identifier is optional. You can specify this, e.g. string | number, for platforms and libraries that accepts any numeric value as length with a specific unit.

	Default	Hyphen	Fallback	HyphenFallback
All	Properties	PropertiesHyphen	PropertiesFallback	PropertiesHyphenFallback
Standard	StandardProperties	StandardPropertiesHyphen	StandardPropertiesFallback	StandardPropertiesHyphenFallback
Vendor	VendorProperties	VendorPropertiesHyphen	VendorPropertiesFallback	VendorPropertiesHyphenFallback
Obsolete	ObsoleteProperties	ObsoletePropertiesHyphen	ObsoletePropertiesFallback	ObsoletePropertiesHyphenFallback
Svg	SvgProperties	SvgPropertiesHyphen	SvgPropertiesFallback	SvgPropertiesHyphenFallback

Categories:

• All - Includes Standard, Vendor, Obsolete and Svg
• Standard - Current properties and extends subcategories StandardLonghand and StandardShorthand (e.g. StandardShorthandProperties)
• Vendor - Vendor prefixed properties and extends subcategories VendorLonghand and VendorShorthand (e.g. VendorShorthandProperties)
• Obsolete - Removed or deprecated properties
• Svg - SVG-specific properties

Variations:

• Default - JavaScript (camel) cased property names
• Hyphen - CSS (kebab) cased property names
• Fallback - Also accepts array of values e.g. string | string[]

At-rule types

At-rule interfaces with descriptors.

	Default	Hyphen	Fallback	HyphenFallback
@counter-style	CounterStyle	CounterStyleHyphen	CounterStyleFallback	CounterStyleHyphenFallback
@font-face	FontFace	FontFaceHyphen	FontFaceFallback	FontFaceHyphenFallback
@page	Page	PageHyphen	PageFallback	PageHyphenFallback
@viewport	Viewport	ViewportHyphen	ViewportFallback	ViewportHyphenFallback

Pseudo types

String literals of pseudo classes and pseudo elements

• Pseudos

  Extends:

  • AdvancedPseudos

    Function-like pseudos e.g. :not(:first-child). The string literal contains the value excluding the parenthesis: :not. These are separated because they require an argument that results in infinite number of variations.

  • SimplePseudos

    Plain pseudos e.g. :hover that can only be one variation.

Usage

Length defaults to string | 0. But it's possible to override it using generics.

import * as CSS from 'csstype';

const style: CSS.Properties<string | number> = {
  padding: 10,
  margin: '1rem',
};

In some cases, like for CSS-in-JS libraries, an array of values is a way to provide fallback values in CSS. Using CSS.PropertiesFallback instead of CSS.Properties will add the possibility to use any property value as an array of values.

import * as CSS from 'csstype';

const style: CSS.PropertiesFallback = {
  display: ['-webkit-flex', 'flex'],
  color: 'white',
};

There's even string literals for pseudo selectors and elements.

import * as CSS from 'csstype';

const pseudos: { [P in CSS.SimplePseudos]?: CSS.Properties } = {
  ':hover': {
    display: 'flex',
  },
};

Hyphen cased (kebab cased) properties are provided in CSS.PropertiesHyphen and CSS.PropertiesHyphenFallback. It's not not added by default in CSS.Properties. To allow both of them, you can simply extend with CSS.PropertiesHyphen or/and CSS.PropertiesHyphenFallback.

import * as CSS from 'csstype';

interface Style extends CSS.Properties, CSS.PropertiesHyphen {}

const style: Style = {
  'flex-grow': 1,
  'flex-shrink': 0,
  'font-weight': 'normal',
  backgroundColor: 'white',
};

What should I do when I get type errors?

The goal is to have as perfect types as possible and we're trying to do our best. But with CSS Custom Properties, the CSS specification changing frequently and vendors implementing their own specifications with new releases sometimes causes type errors even if it should work. Here's some steps you could take to get it fixed:

If you're using CSS Custom Properties you can step directly to step 3.

1. First of all, make sure you're doing it right. A type error could also indicate that you're not :wink:

   • Some CSS specs that some vendors has implemented could have been officially rejected or haven't yet received any official acceptance and are therefor not included
   • If you're using TypeScript, type widening could be the reason you get Type 'string' is not assignable to... errors

2. Have a look in issues to see if an issue already has been filed. If not, create a new one. To help us out, please refer to any information you have found.

3. Fix the issue locally with TypeScript (Flow further down):

   • The recommended way is to use module augmentation. Here's a few examples:

     // My css.d.ts file
     import * as CSS from 'csstype';
     
     declare module 'csstype' {
       interface Properties {
         // Add a missing property
         WebkitRocketLauncher?: string;
     
         // Add a CSS Custom Property
         '--theme-color'?: 'black' | 'white';
     
         // ...or allow any other property
         [index: string]: any;
       }
     }
     

   • The alternative way is to use type assertion. Here's a few examples:

     const style: CSS.Properties = {
       // Add a missing property
       ['WebkitRocketLauncher' as any]: 'launching',
     
       // Add a CSS Custom Property
       ['--theme-color' as any]: 'black',
     };
     

   Fix the issue locally with Flow:

   • Use type assertion. Here's a few examples:

     const style: $Exact<CSS.Properties<*>> = {
       // Add a missing property
       [('WebkitRocketLauncher': any)]: 'launching',
     
       // Add a CSS Custom Property
       [('--theme-color': any)]: 'black',
     };
     

Version 2.0

The casing of CSS vendor properties are changed matching the casing of prefixes in Javascript. So all of them are capitalized except for ms.

• msOverflowStyle is still msOverflowStyle
• mozAppearance is now MozAppearance
• webkitOverflowScrolling is now WebkitOverflowScrolling

More info: https://www.andismith.com/blogs/2012/02/modernizr-prefixed/

Contributing

Never modify index.d.ts and index.js.flow directly. They are generated automatically and committed so that we can easily follow any change it results in. Therefor it's important that you run $ git config merge.ours.driver true after you've forked and cloned. That setting prevents merge conflicts when doing rebase.

Commands

• yarn build Generates typings and type checks them
• yarn watch Runs build on each save
• yarn test Runs the tests
• yarn lazy Type checks, lints and formats everything