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/coreBuild 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
| Import | Use |
|---|---|
@puzzle-ui/core | Class names, string casing, responsive values, CSS and color helpers, formatting, and shared utilities. |
@puzzle-ui/core/rendering | Framework-neutral rendering strategies, visibility contracts, and optimization policies. |
@puzzle-ui/core/resources | Resource 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.