Skip to Content

Core Utilities

Use Puzzle's framework-independent TypeScript helpers for class names, responsive values, formatting, rendering, and resource scheduling.

@puzzle-ui/core contains small, framework-independent utilities shared across Puzzle. It has no React dependency, so you can also use it in Node.js, Bun, browser, and edge-runtime code.

Install

npm install @puzzle-ui/core

Build a reusable component helper

Use cn to compose caller-provided classes with conditional states, and use resolveResponsiveValue when an API accepts responsive values. Both helpers are useful in your own components as well as when extending Puzzle components.

import { cn, resolveResponsiveValue } from "@puzzle-ui/core";

const getCardProps = (isFeatured: boolean, className?: string) => ({
  className: cn(
    "product-card",
    isFeatured && "product-card--featured",
    className,
  ),
  direction: resolveResponsiveValue({
    mobile: "col",
    tablet: "row",
  }),
});

cn removes falsey class values and joins the remaining strings. Responsive values are expanded using Puzzle's shared breakpoints, so consumers receive a consistent value at each breakpoint.

Format values for a locale

Pass the locale explicitly to the Intl-based formatters. For dates, pass the same time zone on the server and client to keep rendered output consistent.

import {
  formatCurrency,
  formatDateRange,
  type DateRange,
} from "@puzzle-ui/core";

const stay: DateRange = {
  start: new Date("2026-06-10T00:00:00.000Z"),
  end: new Date("2026-06-14T00:00:00.000Z"),
};

const price = formatCurrency(425, "EUR", "nl-NL");
const dates = formatDateRange(stay, "nl-NL", {
  dateStyle: "medium",
  timeZone: "Europe/Amsterdam",
});

These helpers format values; they do not translate labels or choose a locale for your application. Use @puzzle-ui/i18n when you need typed translations and locale resolution.

Public entry points

ImportUse
@puzzle-ui/coreClass names, string casing, responsive values, CSS and color helpers, formatting, and shared utilities.
@puzzle-ui/core/renderingFramework-neutral rendering strategies, visibility contracts, and optimization policies.
@puzzle-ui/core/resourcesResource scheduler contracts and helpers.

Use only these package entry points rather than importing files from the package source. For a themed interface, continue with Theme and UI components; for reusable interactions, see Hooks.