Trackunit css-class-variance-utilities

The @trackunit/css-class-variance-utilities package is a thin wrapper around the upstream cva package with tailwind-merge wired into its onComplete hook, so later conflicting utilities win and callers do not need to call twMerge themselves. Use cva for a variant table and cx from this package to join class strings — both go through that hook.

Usage

Import cva and cx from this package rather than from cva directly:

import { cva } from "@trackunit/css-class-variance-utilities";

export const cvaPage = cva({
  base: ["grid", "h-full"],
  variants: {
    layout: {
      content: ["grid-rows-1"],
      none: [],
    },
  },
  defaultVariants: { layout: "none" },
});

Because cx goes through the same hook, it resolves conflicts too: cx("p-2", "p-4") returns "p-4".

Authoring guide (what to write in a .variants.ts file, and when to use cx): Storybook Foundations → Styling variants.

To compose variant functions, use the composes property on a cva config.

Migrating from cvaMerge

cvaMerge is gone. There is no compatibility shim: bumping this package without running the migration is a compile failure, not a deprecation warning.

The old call took the base classes as a positional argument; cva takes a single config object with a base property:

// before
cvaMerge(["grid", "h-full"], { variants: { … } });
// after
cva({ base: ["grid", "h-full"], variants: { … } });

Run these two commands in the consuming repo after bumping the dependency:

nx g @trackunit/migrations:migrate
nx g @trackunit/migrations:run-migrations

migrate discovers this package's pending migration and writes it to trackunit-migrations.json. run-migrations applies it. A second run is a no-op — already-applied identities are recorded and skipped.

The codemod rewrites the imports and the call shape, preserving comments and formatting. Any call site it can't rewrite with confidence — a base or config built at runtime, or an aliased import — is left untouched and printed with its file and line. Fix those by hand; the run never guesses at classnames it wasn't sure about.

null variant props

cva 0.7 accepted null for a variant prop and suppressed that variant. cva 1.0's types reject null, and at runtime null falls through to the variant's defaultVariants entry. The codemod rewrites variant definitions, not their consumers, so these surface as type errors after migrating.

undefined is the replacement, but the two are only equivalent when that variant key has no defaultVariants entry. Where a default exists, undefined silently applies the default class instead of no class.

Pinned prerelease

This package depends on [email protected], pinned exactly (no caret). The bare cva npm name's latest dist-tag resolves to an unrelated squatted package, and a future stable 1.0.0 may require another migration — the composition primitive in particular has already changed shape between betas.

For more info and a full guide on Iris App SDK Development, please visit our Developer Hub.

Development

At this point this library is only developed by Trackunit Employees.
For development related information see the development readme.

Trackunit

This package was developed by Trackunit ApS. Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.