Easy CSS Transform Builder

0.1.0 · active · verified Sun Apr 19

easy-css-transform-builder is a JavaScript/TypeScript utility library designed to simplify the creation of complex CSS `transform` values. It enables developers to define various transform properties like `translateX`, `scale`, `rotate3d`, and `skewY` within a simple JavaScript object, which the library then serializes into a valid CSS `transform` string. The current version is 0.1.0, indicating it is in its initial release phase without an established release cadence, and it ships with TypeScript types for enhanced developer experience. Its key differentiator is its straightforward, fluent API for programmatically generating CSS transform strings, making it particularly useful for dynamic styling and animation integrations within JavaScript-driven UI frameworks, as illustrated by its usage examples.

Common errors

```
TypeError: createCSSTransformBuilder is not a function
```
cause Attempting to use a CommonJS `require` statement for an ESM-first package or an incorrect named import.

fix Use a named ESM import: `import { createCSSTransformBuilder } from 'easy-css-transform-builder';`
```
ReferenceError: builder is not defined
```
cause The `builder` instance was not initialized or is out of scope when attempting to call it.

fix Ensure `createCSSTransformBuilder()` is called to get a builder instance before using it: `const builder = createCSSTransformBuilder();`
```
Argument of type 'number[]' is not assignable to parameter of type '[number, number, number]' for 'translate3d' (or similar TypeScript errors for 3D transforms with incorrect array lengths).
```
cause Providing an array with an incorrect number of elements for 3D transform functions like `translate3d`, `scale3d`, or `rotate3d` (e.g., 2 elements instead of 3 or 4).

fix Ensure array inputs for `translate3d` and `scale3d` have exactly 3 elements, and `rotate3d` has exactly 4 elements (x, y, z, angle).

Warnings

gotcha This package is currently in its very early stages (v0.1.0). While functional, expect potential API changes, limited community support, and unoptimized performance as it matures.
Fix: Review the `CHANGELOG.md` for updates when upgrading, and consider pinning exact package versions to avoid unexpected breaking changes.
gotcha Default units for length (`px`) and angle (`deg`) are applied to number values when not explicitly provided. Be mindful when mixing unit-less numbers with string-based unit values, as implicit units will be added to numbers.
Fix: Always explicitly define units when creating the builder (`createCSSTransformBuilder({ length: 'em', angle: 'rad' })`) or provide string values with units (e.g., `translateX: '50%'`) for each property to ensure the desired CSS output.
gotcha The library does not perform extensive validation on input values for transform properties. Providing invalid types (e.g., an object instead of a number for `translateX`) or out-of-range values may lead to unexpected CSS output or runtime errors in the browser.
Fix: Ensure all input values conform to the expected types (number or string) and valid ranges for CSS transform properties as per MDN documentation.

Install

npm install easy-css-transform-builder npm
yarn add easy-css-transform-builder yarn
pnpm add easy-css-transform-builder pnpm

Imports

createCSSTransformBuilder
wrong:
```
const createCSSTransformBuilder = require('easy-css-transform-builder');
```
correct:
```
import { createCSSTransformBuilder } from 'easy-css-transform-builder';
```
This is the primary factory function to initialize the transform builder. The package is ESM-first and ships with types, requiring named imports.
properties
wrong:
```
import properties from 'easy-css-transform-builder/properties';
```
correct:
```
import { properties } from 'easy-css-transform-builder';
```
An array of all supported CSS transform property names. This is useful for introspection or validation and is exposed as a named export.

Quickstart

This quickstart initializes the transform builder with default units and demonstrates how to apply multiple CSS transform properties from an object into a single CSS transform string.

import { createCSSTransformBuilder } from 'easy-css-transform-builder';

// Initialize the builder, optionally setting default units.
const builder = createCSSTransformBuilder({
  length: 'px', // Default for length values
  angle: 'deg'  // Default for angle values
});

// Define your transform properties as an object.
const transformProperties = {
  translateX: 30,
  scale: 2.8,
  rotate3d: [1, 0, 0, 60],
  skewY: '40rad' // Units can be explicitly provided as strings
};

// Generate the CSS transform string.
const cssTransformString = builder(transformProperties);

console.log(cssTransformString);
// Expected output: translateX(30px) scale(2.8) rotate3d(1, 0, 0, 60deg) skewY(40rad)

// Example of dynamic usage (e.g., in a React component's style prop)
const myElementStyle = {
  transform: builder({
    translateX: 100,
    rotate: '45deg'
  })
};
// In a real application, you'd apply myElementStyle to an element.
console.log('Dynamic style transform:', myElementStyle.transform);

view raw JSON →