CSS dimensions
Validate values such as 12px, 1.5rem, or 100% by combining a numeric schema with an enum of permitted units.
Zod · Module
z.templateLiteral
z.templateLiteral creates a Zod schema for strings formed by concatenating literal text and compatible schemas. It validates the complete assembled value and infers a corresponding TypeScript template-literal type.
- Since
- Zod 4.0
How it works
z.templateLiteral builds a schema for strings assembled from literal text and compatible Zod schemas. It combines the accepted patterns of each component, so the resulting validator checks the complete concatenated string while preserving the corresponding template-literal type.
Syntax
z.templateLiteral([literalOrSchema, ...])Parameters
| Name | Type | Description |
|---|---|---|
parts | array | An array of literal strings and Zod schemas whose inferred types are assignable to string, number, bigint, boolean, null, or undefined. |
Returns
A Zod schema representing the concatenated template-literal pattern.
Key points
- Its component list may contain any number of literal strings and schemas.
- A literal prefix, a string schema, and a literal suffix produce a matching template-literal schema.
- Literal schemas can contribute non-string values that are stringified in the resulting pattern.
- Nullable literal components are supported, allowing the corresponding stringified alternatives.
- Combining a number schema with an enum is useful for validating unit-bearing strings.
Common mistakes
- Only schemas whose inferred output is assignable to string, number, bigint, boolean, null, or undefined can be components.
- Custom refinements are not incorporated into the generated template-literal validation pattern.
Example: Validate a CSS length
import { z } from "zod";
const cssLength = z.templateLiteral([
z.number(),
z.enum(["px", "em", "rem"]),
]);
cssLength.parse("12px"); // "12px"
// cssLength.parse("12pt"); // throws
This schema accepts a number followed by one of the specified CSS units.
When to use it
Structured IDs
Model structured identifiers with fixed prefixes, separators, and constrained dynamic sections.
Template-literal typing
Represent TypeScript template-literal types that ordinary string schemas cannot express.
Interview questions
QHow do you construct a template-literal schema?
Pass an array containing literal strings and compatible Zod schemas. Zod combines their patterns into one validator for the concatenated string.
Follow-up: Which component types are allowed? Any schema whose inferred type is assignable to string, number, bigint, boolean, null, or undefined.
QWhat type and runtime behavior does it provide?
The resulting type follows the template structure, such as ${number}px for a number schema followed by the literal "px". Parsing validates the entire assembled value.
Follow-up: Can a finite set of suffixes be modeled? Yes; use an enum schema, such as z.enum(["px", "em", "rem"]), after the numeric component.
QHow are component schemas enforced?
Zod uses the internal regular-expression representation of stringifiable schemas and concatenates those patterns into a super-regex. This means supported formats and constraints represented there participate in validation.
Follow-up: Do refinements participate too? No; the documentation specifically excludes custom refinements from this mechanism.
Related
z.string()z.literal()z.number()z.enum()z.nullable()