DEV Community: Serban Dan Rusu

Romanian Address Format: The Rules and a React Form

Serban Dan Rusu — Fri, 06 Nov 2026 07:00:00 +0000

TL;DR

The Romanian address format starts with the street line (type, name, number, then bl., sc., et. and ap. for block, staircase, floor and apartment), adds the sector in Bucharest, and ends with the 6-digit postal code, the locality and, in domestic use, the county as jud. Cluj. The first two digits of the postal code identify the county, so a form can flag a code from the wrong one. In React, build it as a county select, a locality search that ignores diacritics, street and number, an optional block row and a numeric postal code.

Search for an address form React example and you get a US layout: street, city, state, ZIP. Ship that to customers in Romania and they have nowhere to put the block, the staircase or the Bucharest sector, so the courier calls to ask. This tutorial covers the Romanian address format part by part, checked against the Universal Postal Union's sheet for Romania, with English labels and Romanian data. Then it builds the form in React on Address Input, a component from Wingo UI, the library we build, so we are not neutral.

What is the Romanian address format?

A Romanian address runs from the most specific line to the broadest: the street line with the building details, the sector in Bucharest, then the postal code and the locality. The UPU addressing sheet for Romania (dated October 2007) gives four rules:

The street type comes before the name: Str. (strada), Bd. (bulevardul), Calea, Aleea, Șos. (șoseaua).
The number usually ends the street line.
Building details can go at the end of the same line: block, staircase, floor, apartment.
In Bucharest, the sector can sit on its own line between the street and the locality.

The 6-digit postal code goes to the left of the locality. Here is a Romania address format example from the sheet for an apartment in Bucharest, and one for an office in Craiova:

ASTRA
Drumul Taberei nr. 35, bl. F5, sc. 2, parter, ap. 23
Sector 6
061357 BUCHAREST
ROMANIA

SC PASAJ SA
Str. Bariera Valcii, nr. 215
200716 CRAIOVA
ROMANIA

The sheet writes Valcii for Vâlcii, which matters for search later. Both stop at the locality, since the postal code implies the county. In domestic mail, invoices and courier forms, people add the county (județ) after the locality as jud. Cluj, which also tells apart villages that share a name. Here is the Romanian postal address format as form fields, with English labels:

Form label	Romanian	Written as
County	județ	jud. Cluj
Sector	sector (București only)	Sector 6
City or village	municipiu, oraș, comună, sat	Cluj-Napoca, sat Vâlcele
Street	stradă, bulevard, calea, aleea	Str. Memorandumului
No.	număr	nr. 28
Block	bloc	bl. A2
Entrance	scară	sc. 1
Floor	etaj	et. 3, or parter for the ground floor
Apt.	apartament	ap. 12
Postal code	cod poștal	400114

The labels are Address Input's English defaults. We label the scară "Entrance" because each staircase of a block has its own door, which is what a courier looks for.

How do you write a Bucharest or village address?

In Bucharest the sector takes the place of the county, and in the countryside a village usually needs its commune as well. București is a municipality with the rank of a county, split into six sectors. Written on one line, as a courier form or an invoice prints it, a Bucharest address ends with "Sector 6, 061357 București" and has no jud. part.

Villages add a level. Counties contain municipalities (municipii), towns (orașe) and communes (comune), and a commune groups several villages (sate). The National Institute of Statistics keeps the official list as SIRUTA, a register on those three levels that it publishes as a CSV on data.gov.ro. A village address names the village and usually its commune, as in "sat Vâlcele, com. Feleacu, jud. Cluj": Feleacu is a commune of five villages, one of them Vâlcele. In many rural communities there are no street names at all.

RoAddress, the value type, has no commune field. Keep the village in locality and its SIRUTA code in localityId: the register links every village to its commune, so you can print the commune when a courier needs it.

How do Romanian postal codes relate to counties?

The first two digits of a Romanian postal code identify the county, or the sector in Bucharest. Romania moved to 6-digit codes on May 1, 2003, and the UPU sheet reads them as a postal region, a district of that region (or a sector in Bucharest), then the delivery area. Per Wikipedia's article on postal codes in Romania, cities of more than 50,000 people get a code per street or small group of addresses, a smaller town has one code for the whole town, and village codes have a 7 as their third digit, like Feleacu's 407270. Poșta Română's postal code search finds the full code for an address.

Here is the Romanian counties list with the ISO 3166-2:RO code (the letters on license plates) and the postal prefix. Address Input stores the county as this code, and the prefixes match its RO_POSTAL_PREFIXES:

County	Code	Postal prefix
Alba	AB	51
Arad	AR	31
Argeș	AG	11
Bacău	BC	60
Bihor	BH	41
Bistrița-Năsăud	BN	42
Botoșani	BT	71
Brașov	BV	50
Brăila	BR	81
București	B	01 to 06 (Sector 1 to 6)
Buzău	BZ	12
Caraș-Severin	CS	32
Călărași	CL	91
Cluj	CJ	40
Constanța	CT	90
Covasna	CV	52
Dâmbovița	DB	13
Dolj	DJ	20
Galați	GL	80
Giurgiu	GR	08
Gorj	GJ	21
Harghita	HR	53
Hunedoara	HD	33
Ialomița	IL	92
Iași	IS	70
Ilfov	IF	07
Maramureș	MM	43
Mehedinți	MH	22
Mureș	MS	54
Neamț	NT	61
Olt	OT	23
Prahova	PH	10
Satu Mare	SM	44
Sălaj	SJ	45
Sibiu	SB	55
Suceava	SV	72
Teleorman	TR	14
Timiș	TM	30
Tulcea	TL	82
Vaslui	VS	73
Vâlcea	VL	24
Vrancea	VN	62

That gives a cheap check. If someone picks Iași and types a code that starts with 40, one of the two is wrong: postalCodeMatchesCounty("400114", "IS") returns false. In Bucharest a chosen sector narrows it to one prefix, so postalCodeMatchesCounty("061357", "B", "6") is true and the same code with sector "3" is false.

Address Input shows a mismatch as an amber warning under the postal code once the field loses focus, and the form stays valid. We chose a warning on purpose: the check only knows prefixes, and a person who knows their own code should never be stuck at checkout.

How do I build a Romanian address form in React?

Split it into a county select, a locality search, street and number, an optional block row and a six-digit postal code, then validate on submit and again on the server. Address Input ships those parts. It is a Pro component, so sign in once with npx wingo-ui@latest login on a Pro account, then run npx wingo-ui@latest add address-input. The CLI adds what it builds on, including ro-locations, text-match, the select and the combobox. The component renders the county, the locality, street and number, a collapsed row for block, staircase, floor and apartment, the postal code and a details field for the intercom or a landmark. Its labels follow the locale (the locale prop, then the provider, then the page language): English, or Romanian for ro.

A checkout step that validates on submit and saves through the Server Action shown further down:

// app/checkout/shipping-step.tsx
"use client";

import { useState } from "react";
import {
  AddressInput,
  EMPTY_RO_ADDRESS,
  validateRoAddress,
  type AddressErrors,
  type RoAddress,
} from "@/components/ui/address-input";
import { Button } from "@/components/ui/button";
import { saveShipping } from "./actions";

export function ShippingStep({ onDone }: { onDone: () => void }) {
  const [address, setAddress] = useState<RoAddress>(EMPTY_RO_ADDRESS);
  const [errors, setErrors] = useState<AddressErrors>();

  return (
    <form
      noValidate
      className="flex flex-col gap-4"
      onSubmit={async (event) => {
        event.preventDefault();
        // the submit already made AddressInput show every error
        if (!validateRoAddress(address).valid) return;
        const result = await saveShipping(address);
        if (result.ok) onDone();
        else setErrors(result.errors);
      }}
    >
      <AddressInput
        label="Delivery address"
        value={address}
        errors={errors}
        onValueChange={(next) => {
          setAddress(next);
          setErrors(undefined);
        }}
        showSummary
      />
      <Button type="submit">Continue to payment</Button>
    </form>
  );
}

showSummary prints formatRoAddress under the form, the way the courier will read it: Str. Memorandumului 28, bl. A2, sc. 1, et. 3, ap. 12, 400114 Cluj-Napoca, jud. Cluj.

The parts a hand-rolled form usually misses:

Phones. The county and locality lists open as bottom sheets below 768px, the postal code takes six digits with the numeric keypad, and Enter moves to the next part.
Autofill. The county uses address-level1, the locality address-level2, the street address-line1 and the code postal-code, so a saved browser address fills the parts.
Paste. "Str. Memorandumului nr. 28, bl. A2" pasted into the street fills the street, number and block.
County changes. Picking București swaps the locality for a sector select. Changing the county clears the locality and a postal code from another county, and keeps the street and number.

Live demo: Address Input. The original article embeds an interactive demo here (Clear the postal code, type six digits that start with 70, the prefix of Iași, and press Tab: the county is Cluj, so a warning appears while the readout still says valid. Then pick București as the county to get the sector select). Try it live on wingo-ui.com or open the Address Input docs. Install: npx wingo-ui@latest add address-input

How do I search localities without diacritics?

Fold both strings before you compare them: lowercase, decompose with NFD and drop the combining marks. "Iași".includes("iasi") is false, and folded, both sides read iasi. Ș and ț with a comma below only arrived in Unicode 3.0 in 1999, and older encodings had only the cedilla forms ş and ţ, which still turn up in imported data. Both decompose to a base letter plus a combining mark, so NFD folding treats Ștefănești, Ştefăneşti and stefanesti as one name.

text-match does that folding, ranks matches (exact, prefix, word prefix, inside a word) and returns the ranges to highlight, in about 200 lines with no dependencies. ro-locations builds its searchLocations on it, and Address Input's locality combobox filters with it.

Live demo: Romanian locations. The original article embeds an interactive demo here (Type iasi, manastur or sector 3 without diacritics: each finds its place, with the matched letters highlighted). Try it live on wingo-ui.com or open the Romanian locations docs. Install: npx wingo-ui@latest add ro-locations

Folding does not cover abbreviations or old spellings. People type "Tg. Mureș" for Târgu Mureș, and records from before the 1993 spelling rule write î inside words (Tîrgu). filterByText takes keywords next to the label, so aliases handle both:

// lib/locality-search.ts
import { filterByText } from "@/lib/text-match";

// county is the plate code ("CJ"), the code Address Input stores and passes to loadLocalities
export type Locality = { id: string; name: string; county: string; commune?: string };

// how people also write a name: "Tg. Mures", and "Tirgu" from before the 1993 spelling rule
function aliases(name: string) {
  return [name.replace(/^Târgu /, "Tg. "), name.replace(/(?<=\p{L})â(?=\p{L})/gu, "î")];
}

export function searchLocalities(list: readonly Locality[], county: string, query: string) {
  return filterByText(
    list.filter((locality) => locality.county === county),
    query,
    (locality) => [locality.name, ...aliases(locality.name)],
    { limit: 20 },
  );
}

Now "tg mures" and "tirgu mures" both find Târgu Mureș, ranked a little below a direct hit on the name.

How do I load every village from SIRUTA?

Serve the SIRUTA list from your own route and give Address Input a loadLocalities function that queries it. Without one, the component searches a built-in list of 332 cities, towns and large communes and accepts any other locality as typed, with a quiet note under the field. text-match has no "use client" directive, so the same search runs in a route handler:

// app/api/localities/route.ts
import type { NextRequest } from "next/server";
import { LOCALITIES } from "@/data/localities"; // built from the SIRUTA CSV
import { searchLocalities } from "@/lib/locality-search";

export function GET(request: NextRequest) {
  const params = request.nextUrl.searchParams;
  const results = searchLocalities(LOCALITIES, params.get("county") ?? "", params.get("q") ?? "");
  return Response.json(
    results.map(({ item }) => ({
      value: item.id,
      label: item.name,
      // tells apart villages with the same name
      description: item.commune && `com. ${item.commune}`,
    })),
  );
}

<AddressInput
  label="Delivery address"
  loadLocalities={async (county, query, { signal }) => {
    const params = new URLSearchParams({ county, q: query });
    const response = await fetch(`/api/localities?${params}`, { signal });
    return response.ok ? response.json() : [];
  }}
/>

The value you return becomes localityId, so the SIRUTA code is saved with the address.

How do I validate the address on the server?

Check it again in the Server Action, with a zod 4 schema (npm install zod) in a file that has no "use client". Copied component code has a trap here: address-input.tsx starts with "use client", so on the server every export is a client reference. Calling validateRoAddress or formatRoAddress in a Server Component or a Server Action throws "Attempted to call formatRoAddress() from the server but formatRoAddress is on the client". Type imports are fine, and ro-locations has no directive, so the schema can use its county lookup:

// lib/ro-address-schema.ts
import { z } from "zod";
import { getCounty } from "@/lib/ro-locations";

const text = z.string().trim();

export const roAddressSchema = z
  .object({
    county: text.refine((code) => Boolean(getCounty(code)), { error: "Choose a county from the list" }),
    locality: text,
    localityId: text.optional(),
    sector: z.enum(["1", "2", "3", "4", "5", "6"]).optional(),
    street: text.min(1, { error: "Enter the street" }),
    number: text.min(1, { error: "Enter the number" }),
    building: text.optional(),
    entrance: text.optional(),
    floor: text.optional(),
    apartment: text.optional(),
    postalCode: z.union([z.literal(""), z.string().regex(/^\d{6}$/, { error: "A postal code has 6 digits" })]).optional(),
    details: text.optional(),
  })
  // bucharest has sectors where other counties have localities
  .refine((a) => a.county.toUpperCase() !== "B" || Boolean(a.sector), { error: "Choose a sector", path: ["sector"] })
  .refine((a) => a.county.toUpperCase() === "B" || a.locality.length > 0, {
    error: "Enter the city or village",
    path: ["locality"],
  });

// app/checkout/actions.ts
"use server";

import type { AddressErrors } from "@/components/ui/address-input";
import { roAddressSchema } from "@/lib/ro-address-schema";

export async function saveShipping(input: unknown): Promise<{ ok: true } | { ok: false; errors: AddressErrors }> {
  const parsed = roAddressSchema.safeParse(input);
  if (!parsed.success) {
    // the first message per field, the shape of AddressInput's errors prop
    const errors: AddressErrors = {};
    for (const issue of parsed.error.issues) errors[issue.path[0] as keyof AddressErrors] ??= issue.message;
    return { ok: false, errors };
  }
  // save parsed.data with the order
  return { ok: true };
}

Errors from the action land on the matching part through the errors prop and win over the component's own. To format an address on the server for an order email, move formatRoAddress and its helpers into a module without the directive. You own the source.

What should I build next?

Try the postal code check in the demo above, then add the form to your checkout with npx wingo-ui@latest add address-input. Address Input and ro-locations are part of Wingo UI Pro ($8 a month, $80 a year or $150 once as of October 2026), and text-match is free. If the same checkout takes company details, Romanian CUI validation covers tax IDs and the IBAN validation guide covers bank accounts, while React form components explains the label, hint and error anatomy every part of this form shares. More step-by-step React builds live in the Build it category.

Components in this post

Address Input (Pro): A Romanian address form: county, locality search, street, number, block and apartment, postal code checked against the county. Install: npx wingo-ui@latest add address-input
Romanian locations (Pro): Romania's counties, cities and neighbourhoods with coordinates, diacritic-free search, distances and within-radius lists. Install: npx wingo-ui@latest add ro-locations
Text match (Free): Search that ignores case and diacritics, ranks the best matches first and returns the ranges to highlight. Install: npx wingo-ui@latest add text-match

FAQ

How do you write an address in Romania?

Write the street type, name and number first (Str. Memorandumului 28), then the block, staircase, floor and apartment on the same line (bl. A2, sc. 1, et. 3, ap. 12). The next line holds the 6-digit postal code and the locality (400114 Cluj-Napoca), followed in domestic use by the county as jud. Cluj, and in Bucharest a Sector line goes above the postal code. Mail from abroad ends with ROMANIA on its own line.

How many digits does a Romanian postal code have?

Six. Six-digit codes replaced the four-digit ones on May 1, 2003. The first two digits identify the county, and in Bucharest they identify the sector, from 01 for Sector 1 to 06 for Sector 6.

What do bl., sc., et. and ap. mean in a Romanian address?

They abbreviate bloc (the apartment building), scară (the staircase, which has its own entrance), etaj (the floor) and apartament (the apartment). The ground floor is written parter.

How many counties does Romania have?

Romania has 41 counties (județe) plus the municipality of Bucharest, which is divided into six sectors. Their ISO 3166-2:RO codes, such as RO-CJ for Cluj and RO-B for Bucharest, use the same letters as Romanian license plates.

Should a Romanian address form require diacritics?

No. Accept what people type and match it without diacritics: the UPU's own sample addresses for Romania are written without them, and older data uses the cedilla forms ş and ţ. Store the official spelling from your locality list once the person picks a match.

Are Address Input and the Romanian locations data free?

Address Input and ro-locations are part of Wingo UI Pro. text-match, the diacritic-insensitive search both of them use, is free and installs with npx wingo-ui@latest add text-match.

This article was originally published on the Wingo UI blog: Romanian Address Format: The Rules and a React Form. The original has the live, interactive demos and is kept up to date.

Romanian CNP Validator in TypeScript, Zod and React

Serban Dan Rusu — Thu, 05 Nov 2026 15:00:00 +0000

TL;DR

A Romanian CNP validator checks five things: 13 digits, a first digit from 1 to 9, a birth date that exists and is not in the future, a county code (01 to 48, 51, 52, or 70, which the new civil status system has used since May 2024) and the check digit. The check digit is the sum of the first 12 digits multiplied by the matching digits of 279146358279, mod 11, with a remainder of 10 written as 1. Store a valid CNP encrypted, with a keyed hash for lookups, because a plain SHA-256 of one can be brute forced in about half an hour on one CPU core.

Your checkout, payroll or rental contract form asks for a Romanian personal numeric code (CNP), and a 13-digit regex accepts every typo. A Romanian CNP validator has to check more than the length: a digit for sex and century, a birth date that exists, a county code and a weighted check digit. This tutorial writes that check in TypeScript, decodes the parts, turns it into a zod rule and a React field that validates as you type, and ends with what to do before you store a single CNP. The field is Masked Input from Wingo UI, the library we build, so we are not neutral. The validator is plain TypeScript you can paste anywhere.

What is the cod numeric personal format?

Thirteen digits in seven parts, written S AA LL ZZ JJ NNN C. The Romanian Wikipedia article on the CNP documents each one. Here they are on 1960523123457, the sample code from the demo further down:

Digits	Part	Meaning	In the sample
1	S	Sex and century of birth	1: male, born 1900 to 1999
2 to 3	AA	Year of birth	96
4 to 5	LL	Month of birth	05
6 to 7	ZZ	Day of birth	23
8 to 9	JJ	County code	12: Cluj
10 to 12	NNN	Serial number, 001 to 999	345
13	C	Check digit	7

From 1 to 8, the first digit is odd for men and even for women. 1 and 2 mean born in the 1900s, 3 and 4 in the 1800s, 5 and 6 in the 2000s. 7 and 8 are foreign residents, and for them the century is not encoded. English Wikipedia also lists 9 for foreign citizens; the Romanian article stops at 8, so treat 9 as rare and accept it.

The county codes are 01 to 39 for the counties in alphabetical order (Alba to Vrancea), 40 for Bucharest, 41 to 46 for its six sectors, 47 and 48 for the former sectors 7 and 8, which only appear on old codes, and 51 and 52 for Călărași and Giurgiu. There is no 49 or 50.

And since May 2024 there is 70. Codes generated by Romania's new civil status IT system carry 70 in place of the county for every registration, wherever the person was born. The Ministry of Internal Affairs said in May 2024 that this started with births registered from May 8 in Ilfov county and seven cities, plus the birth records of people who had just become citizens, and that existing codes do not change. The Romanian Wikipedia article now lists 70 as well. Two consequences for your code: a range check of 01 to 52 rejects every code the new system issues, and you can no longer read a county from a new code.

How does the CNP checksum algorithm work?

The CNP check digit is a weighted sum mod 11. Multiply each of the first 12 digits by the digit in the same position of the key 279146358279, add the products and divide by 11. The remainder is the check digit, except that a remainder of 10 becomes 1. Here is the sample worked by hand:

Position	1	2	3	4	5	6	7	8	9	10	11	12
Digit	1	9	6	0	5	2	3	1	2	3	4	5
Key	2	7	9	1	4	6	3	5	8	2	7	9
Product	2	63	54	0	20	12	9	5	16	6	28	45

The products add up to 260, and 260 mod 11 is 7, the last digit of 1960523123457.

The fold of 10 into 1 is where the check gets weaker. Remainders 1 and 10 both produce a 1, so about 2 codes in 11 end in 1, and a typo that moves the sum from one to the other passes. 1960523120031 is valid; change its twelfth digit and 1960523120021 passes too.

We measured it with the checkCnp function below. Over 20,000 random valid codes, we tried every single-digit change and every swap of two neighboring digits. The checksum alone missed 1.7% of the changes, every one of them through the fold, and 1.9% of the swaps. Checking the date and the county as well brought both down to about 1.2%. Of a million random 13-digit strings, 10% passed the checksum and 0.14% passed every check. So about 1 typo in 80 passes every check, which is why the form below also reads the code back to the person.

How do I validate a CNP in JavaScript or TypeScript?

Run the checks in order and say which one failed, so the form can explain the problem instead of printing "invalid". Return the decoded parts from the same pass, so nothing parses the code twice. The code is TypeScript with no dependency; drop the types and it runs as plain JavaScript:

// lib/cnp.ts
export type CnpProblem = "format" | "sex" | "date" | "county" | "checksum";

export type CnpInfo = {
  cnp: string;
  sex: "male" | "female" | null;
  // "1996-05-23"; null for 7 to 9, whose century is not encoded
  birthDate: string | null;
  // "12"; "70" for codes issued by the civil status system since May 2024
  county: string;
  countyName: string | null;
  serial: string;
};

export type CnpCheck = { problem: CnpProblem; info: null } | { problem: null; info: CnpInfo };

const WEIGHTS = [2, 7, 9, 1, 4, 6, 3, 5, 8, 2, 7, 9];

// 01 to 39 in alphabetical order, then Bucharest and its sectors (7 and 8 no longer exist)
const COUNTIES: Record<string, string> = Object.fromEntries(
  [
    "Alba", "Arad", "Argeș", "Bacău", "Bihor", "Bistrița-Năsăud", "Botoșani", "Brașov", "Brăila", "Buzău",
    "Caraș-Severin", "Cluj", "Constanța", "Covasna", "Dâmbovița", "Dolj", "Galați", "Gorj", "Harghita", "Hunedoara",
    "Ialomița", "Iași", "Ilfov", "Maramureș", "Mehedinți", "Mureș", "Neamț", "Olt", "Prahova", "Satu Mare",
    "Sălaj", "Sibiu", "Suceava", "Teleorman", "Timiș", "Tulcea", "Vaslui", "Vâlcea", "Vrancea", "București",
    "București, Sector 1", "București, Sector 2", "București, Sector 3", "București, Sector 4",
    "București, Sector 5", "București, Sector 6", "București, Sector 7", "București, Sector 8",
  ].map((name, i) => [String(i + 1).padStart(2, "0"), name]),
);
COUNTIES["51"] = "Călărași";
COUNTIES["52"] = "Giurgiu";

const CENTURY: Record<string, number> = { "1": 1900, "2": 1900, "3": 1800, "4": 1800, "5": 2000, "6": 2000 };

export function cnpCheckDigit(first12: string): number {
  let sum = 0;
  for (let i = 0; i < 12; i++) sum += Number(first12[i]) * WEIGHTS[i];
  // a remainder of 10 does not fit in one digit, so it becomes 1
  return sum % 11 === 10 ? 1 : sum % 11;
}

// "1996-05-23", or null when that day does not exist
function isoDate(year: number, month: number, day: number): string | null {
  const date = new Date(Date.UTC(year, month - 1, day));
  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return null;
  return date.toISOString().slice(0, 10);
}

// the calendar day in Romania, where the codes are issued
export const todayInRomania = () => new Intl.DateTimeFormat("en-CA", { timeZone: "Europe/Bucharest" }).format(new Date());

export function checkCnp(input: string, today = todayInRomania()): CnpCheck {
  const cnp = input.replace(/[\s.-]/g, "");
  const fail = (problem: CnpProblem): CnpCheck => ({ problem, info: null });
  if (!/^\d{13}$/.test(cnp)) return fail("format");

  const s = cnp[0];
  if (s === "0") return fail("sex");

  const [yy, mm, dd] = [cnp.slice(1, 3), cnp.slice(3, 5), cnp.slice(5, 7)].map(Number);
  let birthDate: string | null = null;
  if (CENTURY[s]) {
    birthDate = isoDate(CENTURY[s] + yy, mm, dd);
    if (!birthDate || birthDate > today) return fail("date");
  } else {
    // 7 to 9: the day has to exist in one of the two centuries it could be from
    const candidates = [2000 + yy, 1900 + yy].map((year) => isoDate(year, mm, dd));
    if (!candidates.some((date) => date && date <= today)) return fail("date");
  }

  const county = cnp.slice(7, 9);
  if (county !== "70" && !COUNTIES[county]) return fail("county");

  if (cnpCheckDigit(cnp) !== Number(cnp[12])) return fail("checksum");

  return {
    problem: null,
    info: {
      cnp,
      sex: s === "9" ? null : Number(s) % 2 === 1 ? "male" : "female",
      birthDate,
      county,
      countyName: COUNTIES[county] ?? null,
      serial: cnp.slice(9, 12),
    },
  };
}

export const isValidCnp = (input: string) => checkCnp(input).problem === null;

checkCnp("1960 523 123 457");
// { problem: null, info: { cnp: "1960523123457", sex: "male", birthDate: "1996-05-23", county: "12", countyName: "Cluj", serial: "345" } }
checkCnp("1960523123458"); // { problem: "checksum", info: null }
checkCnp("1000229123456"); // { problem: "date", info: null }, 1900 was not a leap year
checkCnp("1960523491239"); // { problem: "county", info: null }, there is no county 49
isValidCnp("5240601701230"); // true, county 70

Four details that CNP validation in JavaScript often gets wrong:

The century comes from the first digit. new Date(24, 5, 1) is June 1, 1924, because JavaScript maps two-digit years to the 1900s. Build the full year first, and check that the day survived the round trip, or February 29, 1900 slips through.
A birth date cannot be in the future. 5300101123456 decodes to January 1, 2030. Compare against today in Romania, not in UTC or in the server's zone.
The county list has gaps and a new member. 49 and 50 do not exist, and 70 does.
Codes starting with 7 to 9 have no century. We accept the day if it exists in either century and return birthDate: null instead of guessing, because a wrong guess turns an 11-year-old resident into a 111-year-old.

How do I read the birth date, age and county from a CNP?

Take them from info, and turn them into a sentence the person can compare with their ID card. Reading a valid code back catches the mistake no checksum can: someone typing a valid code that belongs to their spouse.

// lib/cnp.ts (continued)
// "Male, born May 23, 1996, Cluj"
export function describeCnp(info: CnpInfo, locale = "en-US"): string {
  const sex = info.sex === "male" ? "Male" : info.sex === "female" ? "Female" : "Foreign national";
  const born = info.birthDate
    ? `born ${new Intl.DateTimeFormat(locale, { dateStyle: "long", timeZone: "UTC" }).format(new Date(info.birthDate))}`
    : "resident";
  return [sex, born, info.countyName].filter(Boolean).join(", ");
}

// full years on a given day: ageOn("2008-10-10", "2026-10-09") is 17
export function ageOn(birthDate: string, today = todayInRomania()): number {
  const [by, bm, bd] = birthDate.split("-").map(Number);
  const [ty, tm, td] = today.split("-").map(Number);
  return ty - by - (tm < bm || (tm === bm && td < bd) ? 1 : 0);
}

A code with county 70 reads "Male, born June 1, 2024", without a county, which is the truth.

How do I write a zod rule for a CNP?

Wrap checkCnp in a check that maps each problem to its own message, then strip the separators so the database gets the 13 digits. The schema uses zod 4 (.check() and the error param):

// lib/cnp-schema.ts
import { z } from "zod";
import { ageOn, checkCnp, type CnpProblem } from "@/lib/cnp";

const MESSAGES: Record<CnpProblem, string> = {
  format: "A CNP has 13 digits",
  sex: "A CNP starts with a digit from 1 to 9",
  date: "Digits 2 to 7 are not a real birth date",
  county: "Digits 8 and 9 are not a county code",
  checksum: "The last digit does not match. Check for a typo",
};

export const cnp = z
  .string()
  .trim()
  .min(1, { error: "Enter your CNP", abort: true })
  .check((ctx) => {
    const { problem } = checkCnp(ctx.value);
    if (problem) ctx.issues.push({ code: "custom", message: MESSAGES[problem], input: ctx.value });
  })
  .transform((value) => value.replace(/[\s.-]/g, ""));

// for contracts that need an adult; 7 to 9 have no birth date, so ask for one separately
export const adultCnp = cnp.refine(
  (value) => {
    const { info } = checkCnp(value);
    return !info?.birthDate || ageOn(info.birthDate) >= 18;
  },
  { error: "You need to be 18 or older" },
);

"Digits 2 to 7 are not a real birth date" tells the person where to look, which "Invalid CNP" never does. If you use the form-validation lib from Wingo UI Pro, it has rules for CUI and IBAN but none for CNP, so this rule sits next to them: with const v = createValidators(), write z.object({ email: v.email(), iban: v.iban(), cnp }).

How do I build a CNP field that checks as you type?

Use a masked field with a numeric keypad, and show the verdict the moment the 13th digit lands. The cnp preset of Masked Input sets inputMode="numeric" and autoComplete="off", keeps the value to 13 digits, drops spaces, dots and dashes from a paste, and pops in a check or an alert icon once the code is complete. The red ring and aria-invalid wait until the person leaves the field. The preset's own check accepts any county from 01 to 52, so it lets 49 and 50 through and rejects 70. Pass validate={isValidCnp} and the field agrees with the zod rule on every code.

Live demo: Masked Input. The original article embeds an interactive demo here (Type 1960523123457: a check appears once the 13th digit is in. Change the last digit and it turns into an alert; press Save to see the error message). Try it live on wingo-ui.com or open the Masked Input docs. Install: npx wingo-ui@latest add masked-input

Wire it with React Hook Form's Controller (npm install react-hook-form @hookform/resolvers zod). Use Controller, not register: the input element holds the masked text, and the raw digits come through onValueChange:

"use client";

import { Controller, useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { Button } from "@/components/ui/button";
import { MaskedInput } from "@/components/ui/masked-input";
import { checkCnp, describeCnp, isValidCnp } from "@/lib/cnp";
import { cnp } from "@/lib/cnp-schema";

const schema = z.object({ cnp });
type Values = z.output<typeof schema>;

export function IdentityStep({ onSave }: { onSave: (values: Values) => Promise<void> }) {
  const form = useForm<z.input<typeof schema>, unknown, Values>({
    resolver: zodResolver(schema),
    // the first error waits for blur, then the field re-checks on every keystroke
    mode: "onTouched",
    defaultValues: { cnp: "" },
  });

  return (
    <form noValidate onSubmit={form.handleSubmit(onSave)} className="flex flex-col gap-4">
      <Controller
        control={form.control}
        name="cnp"
        render={({ field, fieldState }) => {
          const { info } = checkCnp(field.value);
          return (
            <MaskedInput
              preset="cnp"
              // the same check as the zod rule, so the icon and the error never disagree
              validate={isValidCnp}
              label="CNP (personal numeric code)"
              placeholder="13 digits"
              showMask="focus"
              placeholderChar="·"
              ref={field.ref}
              value={field.value}
              onValueChange={(raw) => field.onChange(raw)}
              onBlur={field.onBlur}
              // read back, so a valid code that is not theirs stands out
              description={info ? describeCnp(info) : "The 13 digits on your ID card."}
              error={fieldState.error?.message}
              enterKeyHint="done"
            />
          );
        }}
      />
      <Button type="submit" loading={form.formState.isSubmitting}>
        Continue
      </Button>
    </form>
  );
}

The field uses 16px text on phones, so iOS does not zoom into it, and grows to 44px on touch screens. Its error replaces the description, sets aria-invalid and links the message with aria-describedby. For onSave, pass a Server Action that stores the code with the vault in the next section; the CNP then travels in a POST body, never in a URL.

Should I collect and store CNPs at all?

Only when a law or a contract needs one. A CNP gives away a birth date and a sex, and on codes issued before 2024 a county, so a leak of it is worse than a leak of an email address. If you only need an age, ask for the birth date. If you send B2C invoices through e-Factura, you do not need it either: since OUG 138/2024 a business may use 0000000000000 when a private buyer gives no tax code, and it is not required to collect CNPs. Accept those 13 zeros before you call checkCnp if the field feeds an invoice.

Live demo: Invoicing. The original article embeds an interactive demo here (The check under the invoice reads 0000000000000 as a buyer who gave no CNP, the placeholder e-Factura accepts on B2C invoices). Try it live on wingo-ui.com or open the Invoicing docs. Install: npx wingo-ui@latest add invoicing

When you do collect it, Romanian Law 190/2018 applies on top of GDPR. Its article 2 lists the CNP as a national identification number, and article 4 sets the rules for processing one. Processing it needs a GDPR legal basis, and when that basis is legitimate interest the law requires four safeguards: technical and organizational measures for data minimization and security, a data protection officer, storage periods with deadlines for deletion, and regular training for the people who handle it. This is not legal advice; your DPO decides what applies to you.

What engineering can do is keep the code out of every place it does not need to be. Start with the storage, because a hash is not anonymization. The space of valid codes is small. Everyone born in the 1900s fits in about 3.6 billion candidates: 36,524 days, 2 sex digits, 50 county codes and 999 serials, with the check digit computed. On one core of our dev server, Node's createHash hashed about 2 million codes a second, so walking the whole century takes about half an hour. Knowing the birth date leaves 99,900 candidates, about 50 milliseconds of hashing.

So store two things: the code encrypted, and a keyed hash for lookups and unique indexes. The key never lives in the database:

// lib/cnp-vault.ts
import "server-only";
import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";

// two 32 byte keys, base64, from your secret manager: openssl rand -base64 32
// read on use, not at import, so next build works on a machine without the secrets
function key(name: "CNP_ENCRYPTION_KEY" | "CNP_LOOKUP_KEY"): Buffer {
  const value = Buffer.from(process.env[name] ?? "", "base64");
  if (value.length !== 32) throw new Error(`${name} must be 32 bytes, base64`);
  return value;
}

// same CNP, same value: for unique indexes and "is this person already a customer"
export function cnpLookupHash(cnp: string): string {
  return createHmac("sha256", key("CNP_LOOKUP_KEY")).update(cnp).digest("base64url");
}

// iv + auth tag + ciphertext in one string; a new iv every time, so equal CNPs never look equal
export function encryptCnp(cnp: string): string {
  const iv = randomBytes(12);
  const cipher = createCipheriv("aes-256-gcm", key("CNP_ENCRYPTION_KEY"), iv);
  const data = Buffer.concat([cipher.update(cnp, "utf8"), cipher.final()]);
  return Buffer.concat([iv, cipher.getAuthTag(), data]).toString("base64");
}

export function decryptCnp(stored: string): string {
  const raw = Buffer.from(stored, "base64");
  const decipher = createDecipheriv("aes-256-gcm", key("CNP_ENCRYPTION_KEY"), raw.subarray(0, 12));
  decipher.setAuthTag(raw.subarray(12, 28));
  return Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString("utf8");
}

// what support screens and receipts show: "•••••••••3457"
export const maskCnp = (cnp: string) => "•".repeat(9) + cnp.slice(-4);

The masked form keeps the serial and the check digit and hides the sex, the birth date and the county. The rest is a checklist:

Never in a URL. Send the code in a POST body. Query strings end up in access logs, browser history and analytics.
Never in logs or error reports. Redact cnp in your logger and in your error tracker's event filter, and check that session replay masks the input.
Never back to the browser. After the save, the client gets maskCnp, and only a server route that needs the full code calls decryptCnp.
A deletion date. Decide when each stored code is deleted, and run the job that deletes it.

Should I use a CNP validator package instead?

Only after you read its county table. Code 70 is recent, and a package that misses it rejects real codes. As of October 2026, the most downloaded CNP package on npm, romanian-personal-identity-code-validator, is at 1.1.4 (published May 19, 2024, MIT, 667 downloads from October 1 to 7, 2026). It decodes the birth date, sex, birthplace and age, depends on Moment.js, and its county table has no 70, so it rejects every code the new system issues. It does list 80, as a code obtained abroad. python-stdnum's ro.cnp module accepts 70, and also 80 to 83, labeled "Unknown". We found no official source for 80 to 83, so the code above leaves them out. If a real customer's code fails on one of them, add it.

lib/cnp.ts is about 100 lines with no dependency, and you can read every rule in it. When the format changes again, you edit one table instead of waiting for a maintainer.

Should I copy this code or install it?

Copy it when you need one field: lib/cnp.ts, the zod rule and the free Input with inputMode="numeric" cover a contract or payroll form. Masked Input, the field from the demo, is part of Wingo UI Pro, and so is the invoicing lib, whose parseCnp and isValidCnp decode the sex, birth date and county, accept 70 and treat 0000000000000 as a buyer without a CNP. They skip the future-date check, so keep checkCnp for the form. Install the field with npx wingo-ui@latest add masked-input.

The other Romanian ids have their own guides: Romanian CUI validation for companies and IBAN validation in JavaScript for bank accounts. For the rest of the form anatomy, read React form components: accessible fields, zod and mobile, or browse more component guides.

Components in this post

Masked Input (Pro): A text field that formats itself as you type or paste: card number, expiry, CVC, IBAN, CNP, postal code or a custom mask. Install: npx wingo-ui@latest add masked-input
Invoicing (Pro): Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP. Install: npx wingo-ui@latest add invoicing
Form validation (Pro): Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks. Install: npx wingo-ui@latest add form-validation
Input (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: npx wingo-ui@latest add input

FAQ

How do I validate a Romanian CNP?

Check that it has 13 digits, that the first digit is 1 to 9, that digits 2 to 7 form a real birth date that is not in the future, and that digits 8 and 9 are a county code (01 to 48, 51, 52 or 70). Then multiply the first 12 digits by 2, 7, 9, 1, 4, 6, 3, 5, 8, 2, 7, 9, add the products and take the sum mod 11, turning 10 into 1; the result must equal the last digit.

What does county code 70 mean in a CNP?

Since May 2024, the codes generated by Romania's new civil status IT system carry 70 in place of the county, whatever the place of birth. Codes issued before keep their county, so a validator that only accepts 01 to 52 rejects every code the new system issues.

Why does the CNP check digit use 1 when the remainder is 10?

The check digit has room for one digit, so a remainder of 10 is written as 1. The cost is that remainders 1 and 10 look the same, so a typo that moves the sum between them still passes; in our test that was 1.7% of single-digit typos.

Can I get someone's age from their CNP?

For codes starting with 1 to 6, yes: the first digit gives the century and digits 2 to 7 the year, month and day. Codes for foreign residents and foreign citizens start with 7, 8 or 9 and do not encode the century, so ask for the birth date when the age matters.

Is it legal to store a CNP in my database?

Romanian Law 190/2018 lists the CNP as a national identification number: you need a GDPR legal basis, and if that basis is legitimate interest you also need data minimization and security measures, a data protection officer, retention periods and staff training. Collect it only when a law or a contract needs it, and ask your DPO before you do.

Do I need the customer's CNP for an e-Factura B2C invoice?

No. Since OUG 138/2024, a business may use 0000000000000, thirteen zeros, when a private buyer gives no tax identification code, and it is not required to collect the CNP.

This article was originally published on the Wingo UI blog: Romanian CNP Validator in TypeScript, Zod and React. The original has the live, interactive demos and is kept up to date.

Romanian CUI Validation in TypeScript, Zod and React

Serban Dan Rusu — Thu, 05 Nov 2026 07:00:00 +0000

TL;DR

Romanian CUI validation is a weighted checksum: strip the optional RO prefix, right-align the digits before the last one against the key 753217532, multiply and add, then take the sum times 10 mod 11, where 10 becomes 0. The result must equal the last digit. A valid check digit only proves the number is well formed, so confirm that the company exists, is still registered and pays VAT with ANAF's public web service.

Your sign-up or invoice form has a field for a Romanian company's tax ID, and a regex for "RO plus digits" accepts every mistyped digit. Romanian CUI validation needs three things: a parser that accepts the many ways people write the number, the weighted check digit, and, when it matters, a lookup that proves the company is real. This tutorial builds all three in TypeScript, then wires them into a zod rule, a React field that validates as you type and a sign-up step that looks the company up at ANAF. The UI uses Input and Field from Wingo UI, the library we build, so we are not neutral. The checksum code is plain TypeScript you can paste anywhere.

What is a CUI, and how does it relate to the CIF and the VAT number?

They are one number with three names. The CUI (Codul Unic de Înregistrare) is the code a Romanian company gets when it registers: 2 to 10 digits, the last of which is a check digit. The CIF (cod de identificare fiscală) is the tax ID, and for a company it is the same digits. When the company is registered for VAT, the Romanian Wikipedia article on the CIF describes the CUI becoming a CIF with the "RO" prefix.

So the Romanian VAT number format is RO followed by the same 2 to 10 digits, as the VAT identification number table on Wikipedia lists it. In a real form you will receive RO12345674, ro 12345674, 12 345 674 and RO-12345674, and all four are the same company.

Two rules follow from that:

Store the digits and a VAT flag, never the string as typed. Print RO + digits when you need the VAT number.
The prefix someone typed is not proof of VAT status. People add RO out of habit. The VAT flag should come from ANAF, as we do further down.

How does the CUI check digit work?

The last digit is computed from the others with a fixed key, 753217532. The Romanian Wikipedia article above describes the validare CUI algorithm, and the source of python-stdnum's stdnum.ro.cui implements the same five steps:

Remove the RO prefix and any spaces, dots or dashes. What is left must be 2 to 10 digits.
Set the last digit aside. That is the check digit.
Pad the remaining digits with zeros on the left until there are nine, so they line up with the right end of the key. (Wikipedia reverses both strings instead, which gives the same pairs.)
Multiply each digit by the key digit in the same position and add the products.
Multiply the sum by 10, take the remainder of dividing by 11, and turn a remainder of 10 into 0. The CUI is valid when this equals the check digit.

Here is 12345674 worked by hand. The body is 1234567, padded to 001234567:

Position	Digit	Key	Product
1	0	7	0
2	0	5	0
3	1	3	3
4	2	2	4
5	3	1	3
6	4	7	28
7	5	5	25
8	6	3	18
9	7	2	14

The sum is 95. 950 mod 11 is 4, which matches the last digit, so RO12345674 is valid and RO12345678 is not.

The case that breaks hand-written validators is the remainder of 10. For 18547290 the products add up to 111, and 1110 mod 11 is 10, so the check digit is 0. A validator that skips the fold rejects every company whose check digit lands there.

How do I validate a CUI in TypeScript?

Parse first, then validate. A parser that returns the digits, the prefix and the verdict gives the form, the zod rule and the lookup the same source of truth:

// lib/cui.ts
export type CuiInfo = {
  // the digits without RO: "12345674"
  digits: string;
  // written with RO, the way a VAT payer quotes it
  vatPayer: boolean;
  valid: boolean;
};

// the test key 753217532, one weight per digit before the check digit
const KEY = [7, 5, 3, 2, 1, 7, 5, 3, 2];

export function parseCui(input: string): CuiInfo | null {
  const clean = input.replace(/[\s.\-/]/g, "").toUpperCase();
  const match = /^(RO)?(\d{2,10})$/.exec(clean);
  if (!match) return null;

  const digits = match[2];
  // right-align the body against the key: "1234567" -> "001234567"
  const body = digits.slice(0, -1).padStart(9, "0");
  let sum = 0;
  for (let i = 0; i < 9; i++) sum += Number(body[i]) * KEY[i];
  // times 10, mod 11, and a remainder of 10 becomes 0
  const control = ((sum * 10) % 11) % 10;

  return {
    digits,
    vatPayer: match[1] === "RO",
    valid: control === Number(digits[digits.length - 1]),
  };
}

export function isValidCui(input: string): boolean {
  return parseCui(input)?.valid ?? false;
}

// "ro 1234 5674" -> "RO12345674"; vatPayer adds or drops the prefix
export function formatCui(input: string, options: { vatPayer?: boolean } = {}): string {
  const info = parseCui(input);
  if (!info) return input;
  return `${(options.vatPayer ?? info.vatPayer) ? "RO" : ""}${info.digits}`;
}

parseCui("RO12345674"); // { digits: "12345674", vatPayer: true, valid: true }
isValidCui("12345678"); // false, the check digit should be 4
isValidCui("RO 185 472 90"); // true, remainder 10 becomes 0
formatCui("ro 1234 5674"); // "RO12345674"
formatCui("RO12345674", { vatPayer: false }); // "12345674"

Check four things before you trust a CIF checksum JavaScript snippet from a forum:

It uppercases before it strips RO, or ro12345674 fails.
It turns a remainder of 10 into 0.
It lines the digits up from the right. Left alignment only works for 10 digit codes.
It rejects 11 digits.

python-stdnum also rejects a code that starts with 0. parseCui accepts one, so write the digit group as ([1-9]\d{1,9}) if you want the same rule.

We ran every single-digit change and every swap of two neighboring digits over a large sample of valid 8-digit codes: the check caught about 98% of both, and every missed single-digit typo came from folding 10 into 0. A random 8-digit number passes one time in ten, so a valid check digit never means the company exists.

How do I write a zod rule for a CUI?

Chain three checks and a transform, so the person sees one message at a time and your database always receives the same shape:

// lib/cui-schema.ts
import { z } from "zod";
import { formatCui, isValidCui, parseCui } from "@/lib/cui";

export const cui = z
  .string()
  .trim()
  .min(1, { error: "Enter the company's tax ID", abort: true })
  .refine((value) => parseCui(value) !== null, {
    error: "Use 2 to 10 digits, with or without RO",
    abort: true,
  })
  .refine(isValidCui, { error: "This tax ID fails its check digit" })
  .transform((value) => formatCui(value));

// for a form where the tax ID is optional
export const optionalCui = z.union([z.literal(""), cui]);

abort: true (zod 4) stops at the first failing check, so "abc" says what format is expected instead of also blaming the check digit. The transform turns " ro 1234 5674 " into RO12345674 on submit, so you never have to rewrite the text while someone is typing.

In Wingo UI Pro, the form-validation lib ships a CUI rule as createValidators().cui(), with one message for any invalid code in English, or in Romanian with VALIDATION_MESSAGES_RO. It does not transform, so normalize with formatCui from the invoicing lib before saving; that lib exports the same three functions as the code above, plus IBAN and CNP checks.

How do I build a CUI field that validates as you type?

Show the error after the person leaves the field, then re-check on every keystroke so it clears the moment the number is right. Show the check mark as soon as the number is valid, since it interrupts no one. React Hook Form's onTouched mode gives the error that timing, and useWatch drives the check mark:

"use client";

import { useForm, useWatch } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { CircleCheck } from "lucide-react";
import { z } from "zod";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { isValidCui } from "@/lib/cui";
import { cui } from "@/lib/cui-schema";

const schema = z.object({
  company: z.string().trim().min(1, { error: "Enter the company name" }),
  cui,
});

type Values = z.output<typeof schema>;

export function BillingForm({ onSave }: { onSave: (values: Values) => Promise<void> }) {
  const form = useForm<z.input<typeof schema>, unknown, Values>({
    resolver: zodResolver(schema),
    // the first error waits for blur, then the field re-checks on every keystroke
    mode: "onTouched",
    defaultValues: { company: "", cui: "" },
  });
  const typed = useWatch({ control: form.control, name: "cui" });
  const { errors, isSubmitting } = form.formState;

  return (
    <form noValidate onSubmit={form.handleSubmit(onSave)} className="flex flex-col gap-4">
      <Input
        label="Company name"
        autoComplete="organization"
        {...form.register("company")}
        error={errors.company?.message}
      />
      <Input
        label="Tax ID (CUI)"
        description="With or without RO, for example RO12345674."
        placeholder="RO12345674"
        autoComplete="off"
        autoCapitalize="characters"
        spellCheck={false}
        {...form.register("cui")}
        error={errors.cui?.message}
        rightIcon={isValidCui(typed) ? <CircleCheck className="text-success-soft-foreground" /> : undefined}
      />
      <Button type="submit" loading={isSubmitting}>
        Save
      </Button>
    </form>
  );
}

The field keeps the text keyboard, because a numeric keypad has no R and no O. autoCapitalize="characters" turns "ro" into "RO" on phones, and spell check stays off so the browser does not underline a number. The Input uses 16px text on phones, so iOS does not zoom, and its error replaces the hint, sets aria-invalid and links the message with aria-describedby, the anatomy that Field gives every control. Both are free: npx wingo-ui@latest add input field.

Live demo: Form validation. The original article embeds an interactive demo here (Type RO12345678 in Company tax ID and press Tab: the check digit error appears. Change the last digit to 4 and it clears while you type). Try it live on wingo-ui.com or open the Form validation docs. Install: npx wingo-ui@latest add form-validation

How do I check that the company exists and pays VAT?

Ask ANAF. Its public PlatitorTvaRest web service answers, for a list of CUIs and a date, whether each company is found, its name and address, and whether it was registered for VAT on that date. As of October 2026, the v9 documentation gives these rules: a POST to https://webservicesp.anaf.ro/api/PlatitorTvaRest/v9/tva with a JSON array of { "cui": number, "data": "YYYY-MM-DD" }, at most 100 CUIs per request and at most one request per second per client. The answer has a found list and a notFound list.

We called it on October 8, 2026, and two results surprised us. A number with a wrong check digit lands in notFound without an error, so validating first saves a request against that limit. And our own demo number, RO12345674, came back found: a company struck off the register in 2006, with stare_inregistrare set to "RADIERE din data 29.06.2006", scpTVA false and the inactive flag statusInactivi also false. 18547290, the example from python-stdnum, came back the same way, struck off in 2016. Found does not mean active, and in both records the inactive flag stayed false, so read stare_inregistrare. An active company reads "INREGISTRAT din data" followed by a date.

Keep the call on your server. The field names are Romanian and the version sits in the path (the v5 documentation used /PlatitorTvaRest/api/v5/ws/tva), so one route handler is the only file that changes when ANAF moves. It reads the CUI from the query string, which arrives decoded, and turns a timeout or an error page into one 502:

// app/api/company/route.ts
import type { NextRequest } from "next/server";
import { parseCui } from "@/lib/cui";

const ANAF = "https://webservicesp.anaf.ro/api/PlatitorTvaRest/v9/tva";

type AnafCompany = {
  date_generale: { denumire: string; adresa: string; stare_inregistrare: string };
  inregistrare_scop_Tva: { scpTVA: boolean };
  stare_inactiv: { statusInactivi: boolean };
};

export async function GET(request: NextRequest) {
  const info = parseCui(request.nextUrl.searchParams.get("cui") ?? "");
  // a typo never costs a request against the one-per-second limit
  if (!info?.valid) return Response.json({ error: "invalid-cui" }, { status: 400 });

  // ANAF answers for a calendar day in Romania, not in UTC
  const today = new Intl.DateTimeFormat("en-CA", { timeZone: "Europe/Bucharest" }).format(new Date());
  let found: AnafCompany[];
  try {
    const response = await fetch(ANAF, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify([{ cui: Number(info.digits), data: today }]),
      signal: AbortSignal.timeout(8000),
    });
    if (!response.ok) throw new Error(`ANAF answered ${response.status}`);
    ({ found } = (await response.json()) as { found: AnafCompany[]; notFound: number[] });
  } catch {
    // a timeout, an error status or a page that is not JSON
    return Response.json({ error: "anaf-unavailable" }, { status: 502 });
  }

  const company = found[0];
  if (!company) return Response.json({ error: "not-found" }, { status: 404 });

  return Response.json({
    name: company.date_generale.denumire,
    address: company.date_generale.adresa,
    vatPayer: company.inregistrare_scop_Tva.scpTVA,
    // "INREGISTRAT din data ..." while active, "RADIERE din data ..." once struck off
    struckOff: company.date_generale.stare_inregistrare.startsWith("RADIERE"),
    inactive: company.stare_inactiv.statusInactivi,
  });
}

To ANAF, your server is the client, so every sign-up shares that one request per second. Cache answers by CUI, and for imports batch up to 100 CUIs per request.

ANAF tells you about Romanian VAT registration. For a Romanian VAT ID check on a cross-border invoice inside the EU, use VIES. The European Commission's VIES page lists three reasons for an invalid answer: the number does not exist, it has not been activated for intra-EU transactions, or the registration is not finalized yet. A company can be a valid Romanian VAT payer and still be invalid in VIES.

What does a real sign-up step with a CUI lookup look like?

The Register Page block has an optional company step built on these pieces. Its CUI field validates with v.cui() and looks up only on Enter or the Search button: since one random number in ten passes the check, a lookup on every valid keystroke would also fire on half-typed numbers. An invalid check digit shows the error and never calls the lookup. A valid number goes through formatCui to your onLookupCui. A match fades in the name, the address and a VAT badge, and the field is rewritten with formatCui(cui, { vatPayer }), so the prefix comes from ANAF instead of habit. Editing the number clears the result, and a late answer for an older number is ignored.

Plugging in the route handler from the previous section takes one prop. The account, code and company saves stay simulated until you pass onRegister, onVerify and onCompany:

"use client";

import { RegisterPage } from "@/components/blocks/register-page";

export default function SignUpPage() {
  return (
    <RegisterPage
      onLookupCui={async (cui) => {
        const response = await fetch(`/api/company?cui=${encodeURIComponent(cui)}`);
        if (response.status === 404) return null;
        if (!response.ok) throw new Error("Lookup failed");
        const company = await response.json();
        // treat a struck-off company like an unknown one
        if (company.struckOff) return null;
        return { name: company.name, address: company.address, vatPayer: company.vatPayer };
      }}
    />
  );
}

Returning null opens the manual fields with a note, and throwing offers "Try again" and "Fill in by hand". The demo below answers from a sample table instead of ANAF, so its companies are made up.

Live demo: Register Page. The original article embeds an interactive demo here (Type RO12345678 and press Enter: the check digit error appears and no lookup runs. Fix the last digit to 4 and press Enter again: the sample register fills in the company and its VAT badge). Try it live on wingo-ui.com or open the Register Page docs. Install: npx wingo-ui@latest add register-page

The step after it asks for the 6 digit code from the sign-up email; our React OTP input guide covers what that field has to handle.

Should I copy the CUI code or install it?

Copy it when you need one field: lib/cui.ts, the zod rule and the free Input cover a billing or sign-up form. The ready Romanian kit (CUI, IBAN, CNP and VAT math in invoicing, shared messages in form-validation) and the whole sign-up flow are part of Wingo UI Pro. The other two ids have their own guides: IBAN validation in JavaScript for bank accounts and the Romanian CNP validator for people. For the rest of the form anatomy, read React form components: accessible fields, zod and mobile, or browse more component guides.

Components in this post

Invoicing (Pro): Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP. Install: npx wingo-ui@latest add invoicing
Form validation (Pro): Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks. Install: npx wingo-ui@latest add form-validation
Input (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: npx wingo-ui@latest add input
Field (Free): The wrapper every form control shares: label, hint, animated error and counter, fieldsets, and the one box recipe all inputs use. Install: npx wingo-ui@latest add field
Register Page (Pro): The sign-up screen of a CRM: account with password rules, company details from the CUI, email code and a welcome step. Install: npx wingo-ui@latest add register-page

FAQ

What is the difference between a CUI and a CIF?

For a company they are the same digits. The CUI is the registration code the company receives, and the CIF is its tax identification code, written with the RO prefix when the company is registered for VAT. People are identified by their 13 digit CNP, which has its own check digit.

Is RO part of the CUI?

No. RO marks a company registered for VAT and takes no part in the checksum. Strip it before you validate, store the digits, and add RO back when you print the VAT number of a company that ANAF lists as a VAT payer.

How is the CUI check digit calculated?

Pad the digits before the last one to nine digits on the left, multiply them by 7, 5, 3, 2, 1, 7, 5, 3, 2 and add the products. Multiply the sum by 10 and take the remainder mod 11; a remainder of 10 becomes 0, and the result must equal the last digit.

Does a valid CUI mean the company exists?

No. About one random number in ten passes the check. Query ANAF's PlatitorTvaRest web service to see whether the company exists, whether it is still registered and whether it pays VAT on a given date.

How do I check a Romanian VAT number for an EU cross-border invoice?

Search it in VIES, the European Commission's VAT number search. An invalid answer can mean the number does not exist, or that it has not been activated for intra-EU transactions.

This article was originally published on the Wingo UI blog: Romanian CUI Validation in TypeScript, Zod and React. The original has the live, interactive demos and is kept up to date.

E-Factura VAT Calculation in TypeScript and React

Serban Dan Rusu — Wed, 04 Nov 2026 15:00:00 +0000

TL;DR

An e-Factura VAT calculation groups the invoice lines by VAT category and rate, adds their net amounts, and rounds base times rate once per group to two decimals; per-line VAT is informative only. Every document total then has to come from those same rounded numbers, because ANAF's validation checks the sums to the cent even though it lets the VAT of a rate drift by less than 1 leu. Romania's rates since August 1, 2025 are 21% standard and 11% reduced.

Your invoice editor shows a VAT figure, the PDF matches it, and the XML you upload to ANAF still has to follow one rule that line-by-line code misses: an e-Factura VAT calculation groups the lines by VAT rate, adds their net amounts, and rounds the VAT once per group. Every total in the file then has to come from those rounded numbers, to the cent. This tutorial builds that in TypeScript: Romania's VAT rates with their dates, VAT per rate in integer cents, the validation rules that compare totals, and an invoice line editor in React. The UI is Invoice Line Items from Wingo UI, the library we build, so we are not neutral. The per-rate math is plain TypeScript you can paste anywhere.

What are the Romanian VAT rates in 2026?

Two rates, both in force since August 1, 2025: 21% standard and 11% reduced. Law 141/2025 raised the standard rate from 19% and replaced the old 9% and 5% reduced rates with a single 11% rate, apart from a transitional 9% for some housing bought under contracts signed by August 1, 2025, which Law 161/2026 extended from July 31 to September 30, 2026 (Contzilla, August 2026); ANAF's before-and-after table of the Fiscal Code shows both versions of article 291. As of October 2026, ANAF's consolidated Fiscal Code, last updated by Law 170/2026, still reads 21% and 11%.

Rate	Code	Use it for
21%	S	everything that is not exempt or reduced (19% until Jul 31, 2025)
11%	S	the list in art. 291 (2), including medicines for human use, most food, water and sewerage, books and press, hotel stays, restaurant and catering
0%	E	exempt operations, with an exemption reason
0%	AE	reverse charge, with the buyer's VAT id
0%	K	intra-community supplies, with the buyer's VAT id

The code is the VAT category an e-Factura line carries (BT-151): S for standard rated, which covers the reduced rate too, E for exempt, AE for reverse charge and K for intra-community supplies.

Two details matter for code. The 11% list has exceptions inside it: alcoholic drinks, non-alcoholic drinks under NC code 2202, food with added sugar and at least 10 g of sugar per 100 g, and food supplements stay at 21%. So store the rate on each product. And the rate depends on a date: article 291 (4) applies the rate in force when the chargeable event happens, usually the delivery. A correction you issue today for a July 2025 delivery carries 19%, so keep dated rates and let the VAT select offer the old one when a correction needs it:

import { RO_VAT_RATES, type VatRateOption } from "@/lib/invoicing";

// the standard rate by the date of the chargeable event (Fiscal Code art. 291 (4))
const RO_STANDARD_RATE = [
  { from: "2017-01-01", rate: 0.19 },
  { from: "2025-08-01", rate: 0.21 },
];

export const standardRateOn = (isoDate: string) =>
  RO_STANDARD_RATE.findLast((entry) => entry.from <= isoDate)?.rate;

// the VAT select for corrections of supplies made before August 1, 2025
export const RATES_FOR_CORRECTIONS: VatRateOption[] = [
  ...RO_VAT_RATES,
  { value: "19", rate: 0.19, category: "S", label: "19%", description: "Standard rate until Jul 31, 2025" },
];

RO_VAT_RATES from the invoicing lib holds the current five rows of the table above, and the line editor takes any list through its vatRates prop.

Why is e-Factura VAT computed per rate instead of per line?

Because the standard defines it that way. Rule BR-CO-17 of EN 16931, which e-Factura applies, reads: the VAT category tax amount (BT-117) equals the VAT category taxable amount (BT-116) times the rate (BT-119), rounded to two decimals. The Fiscal Code asks for the same on paper: article 319 (20) requires the taxable base for each rate and the VAT amount in lei for each rate. Adding up rounded line VAT gives a different invoice VAT per rate whenever several lines round in the same direction.

Three 21% lines and one 11% line show it:

Line	Net	VAT	Rounded
Courier delivery, 21%	22.50	4.725	4.73
Packaging, 21%	7.50	1.575	1.58
Label printing, 21%	4.50	0.945	0.95
Sum of the 21% lines	34.50		7.26
21% computed once on 34.50	34.50	7.245	7.25
Books, 3 x 14.50, 11%	43.50	4.785	4.79

Each line rounds its half cent up, three times over; the rate rounds once. 7.25 is the VAT for 21% on this invoice, and the line figures can stay on the PDF as information.

How do I compute VAT per rate in TypeScript without float errors?

Keep money in integer cents and divide integers. Math.round(22.5 * 0.21 * 100) / 100 returns 4.72, because 22.5 x 0.21 is stored as 4.7249999999999996. We ran every base from 0.01 to 1,000.00 lei: 1,000 of them have a 21% VAT ending in exactly half a cent, and the float formula rounds 188 of those the wrong way, while toFixed(2) gets 718 wrong. When the numerator is an integer, a half cent is exactly .5:

// lib/vat-per-rate.ts
export type VatLine = {
  quantity: number; // up to 3 decimals: 1.5 hours
  unitPrice: number; // without VAT, in lei, up to 2 decimals
  vatRate: number; // a percent: 21, 11 or 0
};

export type VatRow = { rate: number; netCents: number; vatCents: number };

// an integer divided by a power of 10: half a cent is exactly .5 and rounds away from zero
export const divRound = (numerator: number, denominator: number) =>
  Math.sign(numerator) * Math.round(Math.abs(numerator) / denominator);

export const lineNetCents = (line: VatLine) =>
  divRound(Math.round(line.quantity * 1000) * Math.round(line.unitPrice * 100), 1000);

// 21% of 3450 cents: 3450 x 2100 / 10000 = 724.5, so 725
export const vatCents = (netCents: number, rate: number) =>
  divRound(netCents * Math.round(rate * 100), 10_000);

export function vatPerRate(lines: VatLine[]): VatRow[] {
  const nets = new Map<number, number>();
  for (const line of lines) nets.set(line.vatRate, (nets.get(line.vatRate) ?? 0) + lineNetCents(line));
  return [...nets]
    .map(([rate, netCents]) => ({ rate, netCents, vatCents: vatCents(netCents, rate) }))
    .sort((a, b) => b.rate - a.rate);
}

vatPerRate([
  { quantity: 1, unitPrice: 22.5, vatRate: 21 },
  { quantity: 1, unitPrice: 7.5, vatRate: 21 },
  { quantity: 1, unitPrice: 4.5, vatRate: 21 },
  { quantity: 3, unitPrice: 14.5, vatRate: 11 },
]);
// [{ rate: 21, netCents: 3450, vatCents: 725 }, { rate: 11, netCents: 4350, vatCents: 479 }]

A reversal (storno) line carries negative amounts. Rounding the absolute value keeps -7.245 at -7.25, the same magnitude the validator computes, since BR-CO-17 compares absolute values.

Which e-Factura validation errors check the totals?

BR-CO-10, BR-CO-11, BR-CO-13, BR-CO-14 and BR-CO-15 compare the document totals to the cent, and only BR-S-08, BR-CO-17 and BR-S-09 allow any slack: less than one unit of the invoice currency. We read the rules in the CIUS-RO validation package the Ministry of Finance publishes for e-Factura, ro16931-ubl 1.0.9, which embeds the EN 16931 rules from the European Commission's validation artefacts (version 1.3.8; we rechecked the tolerances below in that release in October 2026):

Rule	What it checks	Slack
BR-CO-10	sum of line nets (BT-106) = the line net amounts (BT-131) added up	none
BR-CO-11	document allowances (BT-107) = the allowance amounts (BT-92) added up	none
BR-CO-13	total without VAT (BT-109) = BT-106 - BT-107 + charges	none
BR-CO-14	VAT total (BT-110) = the VAT of each rate (BT-117) added up	none
BR-CO-15	total with VAT (BT-112) = BT-109 + BT-110	none
BR-S-08	each rate's base (BT-116) = its lines - its allowances + its charges	under 1 unit
BR-CO-17	each rate's VAT = base x rate, rounded to 2 decimals	under 1 unit
BR-S-09	the same, for standard rated rows	under 1 unit
BR-E-08	the base of the exempt row	none
BR-AE-08	the base of the reverse charge row	none
UBL-DT-01	every amount has at most 2 decimals; unit prices are excluded	none

BR-CO-17 accepts a VAT that is less than 1 leu (one unit of the invoice currency) away from base times rate. Summing rounded line VAT therefore passes it on most invoices: each line drifts by half a cent at most, so it takes about 200 lines rounding the same way to reach 1 leu. The e-Factura validation errors come from mixing the two paths: BT-117 from the per-rate breakdown while BT-110 is the sum of line VAT, or BT-112 as the sum of line totals with VAT. Those sums have no tolerance, every rule above is flagged fatal, and one cent apart means an error message comes back instead of a validated invoice. Do not build on the slack either. Your PDF, your database and the buyer's books should all show 7.25.

How do I turn the totals into e-Factura fields?

Derive every field from the same integers, in one order: line nets, the document discount per rate, the base and VAT of each rate, then the document totals. A discount on the whole invoice is the step that breaks mixed-rate invoices. BR-S-08 counts only the allowances that carry the same category and rate as the row, so a 100 lei discount on an invoice with 21% and 11% lines becomes two allowances, one per rate.

computeInvoiceTotals from the invoicing lib already shares a document discount across the lines by value, and the last line takes the remainder so the cents add up. The function below keeps each line's own discount inside BT-131, reads the document share back out per rate, and recomputes the VAT of each rate in cents:

// lib/efactura-totals.ts
import { computeInvoiceTotals, type VatCategory } from "@/lib/invoicing";
import type { InvoiceDocumentDiscount, InvoiceLine } from "@/components/ui/invoice-line-items";
import { vatCents } from "@/lib/vat-per-rate";

type Group = { rate: number; category: VatCategory };

// every amount in cents; rate is the percent the XML carries (BT-119)
export type EFacturaTotals = {
  lines: (Group & { id: string; net: number })[]; // BT-131
  allowances: (Group & { amount: number })[]; // BG-20, one per rate
  breakdown: (Group & { taxable: number; vat: number })[]; // BG-23: BT-116, BT-117
  lineNet: number; // BT-106
  allowanceTotal: number; // BT-107
  taxExclusive: number; // BT-109
  vat: number; // BT-110
  taxInclusive: number; // BT-112
};

const cents = (amount: number) => Math.round(amount * 100);
const percent = (rate: number) => Number((rate * 100).toFixed(2));
const sum = (values: number[]) => values.reduce((a, b) => a + b, 0);
const categoryOf = (rate: number, line: InvoiceLine): VatCategory =>
  line.vatCategory ?? (rate > 0 ? "S" : "E");

// B2B: unit prices without VAT
export function toEFacturaTotals(lines: InvoiceLine[], discount: InvoiceDocumentDiscount | null): EFacturaTotals {
  const totals = computeInvoiceTotals(lines, {
    discount,
    categoryFor: (rate, line) => categoryOf(rate, line as InvoiceLine),
  });
  const groups = new Map<string, Group & { taxable: number; allowance: number }>();

  const outLines = totals.lines.map((line, i) => {
    const group = { rate: percent(line.vatRate), category: categoryOf(line.vatRate, lines[i]) };
    // BT-131 keeps the line's own discount; its share of the document discount becomes an allowance
    const net = cents(line.gross) - cents(line.discount);
    const key = `${group.rate}|${group.category}`;
    const entry = groups.get(key) ?? { ...group, taxable: 0, allowance: 0 };
    entry.taxable += cents(line.net);
    entry.allowance += net - cents(line.net);
    groups.set(key, entry);
    return { ...group, id: line.id, net };
  });

  const breakdown = [...groups.values()].map(({ rate, category, taxable }) => ({
    rate,
    category,
    taxable,
    vat: category === "S" ? vatCents(taxable, rate) : 0,
  }));
  const allowances = [...groups.values()]
    .filter((group) => group.allowance > 0)
    .map(({ rate, category, allowance }) => ({ rate, category, amount: allowance }));

  const lineNet = sum(outLines.map((line) => line.net));
  const allowanceTotal = sum(allowances.map((allowance) => allowance.amount));
  const vat = sum(breakdown.map((row) => row.vat));
  const taxExclusive = lineNet - allowanceTotal;
  return { lines: outLines, allowances, breakdown, lineNet, allowanceTotal, taxExclusive, vat, taxInclusive: taxExclusive + vat };
}

Take the sample invoice from the editor demo further down: 25 licenses at 250 lei with 10% off, 6 hours of training at 320 lei and an e-Factura integration at 1,500 lei, all at 21%, plus 12 printed guides at 64.90 lei at 11%. With a 100 lei document discount, the function returns allowances of 92.07 lei at 21% and 7.93 lei at 11%, bases of 8,952.93 and 770.87, VAT of 1,880.12 and 84.80, and 11,688.72 lei in total.

Live demo: Invoicing. The original article embeds an interactive demo here (A $100 document discount is already set: press + or − on a quantity and the 21% and 11% rows each recompute their VAT from their own base (this demo prices in dollars)). Try it live on wingo-ui.com or open the Invoicing docs. Install: npx wingo-ui@latest add invoicing

Then check the numbers the XML will carry, whatever produced them: an old system, a stored draft, a hand edit. The check runs on the server right before you build the file and answers with the rule ids ANAF's validator uses:

// lib/efactura-preflight.ts
import type { EFacturaTotals } from "@/lib/efactura-totals";
import { vatCents } from "@/lib/vat-per-rate";

const sum = (values: number[]) => values.reduce((a, b) => a + b, 0);

export function preflight(t: EFacturaTotals): string[] {
  const problems: string[] = [];
  if (t.lineNet !== sum(t.lines.map((l) => l.net))) problems.push("BR-CO-10");
  if (t.allowanceTotal !== sum(t.allowances.map((a) => a.amount))) problems.push("BR-CO-11");
  if (t.taxExclusive !== t.lineNet - t.allowanceTotal) problems.push("BR-CO-13");
  if (t.vat !== sum(t.breakdown.map((r) => r.vat))) problems.push("BR-CO-14");
  if (t.taxInclusive !== t.taxExclusive + t.vat) problems.push("BR-CO-15");
  for (const row of t.breakdown) {
    const same = (x: { rate: number; category: string }) => x.rate === row.rate && x.category === row.category;
    const base = sum(t.lines.filter(same).map((l) => l.net)) - sum(t.allowances.filter(same).map((a) => a.amount));
    // intra-community rules are named IC, the others after their category code
    if (row.taxable !== base) problems.push(`BR-${row.category === "K" ? "IC" : row.category}-08 at ${row.rate}%`);
    // ANAF lets this drift by less than 1 leu; we accept 0
    if (row.category === "S" && row.vat !== vatCents(row.taxable, row.rate)) problems.push(`BR-CO-17 at ${row.rate}%`);
  }
  return problems;
}

How do I build the editable invoice lines in React?

Give the editor the lines and read the totals it computes, then recompute on the server. Invoice Line Items edits the lines like a small spreadsheet: a product search that fills unit, price and VAT, a VAT select that defaults to RO_VAT_RATES, a discount per line with a % / lei switch, and drag to reorder. The price cells are a Currency Input, so 1234.5 becomes 1,234.5 as you type and 1,234.50 on blur. Under the lines, the totals show the taxable base, one VAT row per rate and the grand total, all from one computeInvoiceTotals call on every keystroke, and onValueChange(lines, totals) hands you the same numbers. When the editor is narrower than 768px, every line becomes a card: tap it to edit the line in a bottom sheet on phones (a dialog on larger screens), and the totals fold into a Total row that opens the breakdown.

Live demo: Invoice line items. The original article embeds an interactive demo here (Tap a line, change its VAT from 21% to 11% and save it, then open the breakdown under Total: the base and VAT of each rate follow every edit). Try it live on wingo-ui.com or open the Invoice line items docs. Install: npx wingo-ui@latest add invoice-line-items

In a form, the editor's name prop writes the lines as JSON into a hidden input, so a server action receives them with the rest of the form:

// app/invoices/new/invoice-form.tsx
"use client";

import { useActionState, useState } from "react";
import { Alert } from "@/components/ui/alert";
import { Button } from "@/components/ui/button";
import {
  InvoiceLineItems,
  type InvoiceDocumentDiscount,
  type InvoiceProduct,
} from "@/components/ui/invoice-line-items";
import { issueInvoice } from "./actions";

export function InvoiceForm({ products }: { products: InvoiceProduct[] }) {
  const [discount, setDiscount] = useState<InvoiceDocumentDiscount | null>(null);
  const [state, formAction, pending] = useActionState(issueInvoice, { problems: [] });

  return (
    <form action={formAction} className="flex flex-col gap-4">
      <InvoiceLineItems
        name="lines"
        products={products}
        documentDiscount={discount}
        onDocumentDiscountChange={setDiscount}
        currency="RON"
        locale="en-US"
      />
      <input type="hidden" name="discount" value={JSON.stringify(discount)} />
      {state.problems.length > 0 && (
        <Alert tone="danger" title="These totals would fail e-Factura" description={state.problems.join(", ")} />
      )}
      <Button type="submit" loading={pending} className="self-end">
        Issue invoice
      </Button>
    </form>
  );
}

// app/invoices/new/actions.ts
"use server";

import type { InvoiceLine } from "@/components/ui/invoice-line-items";
import { preflight } from "@/lib/efactura-preflight";
import { toEFacturaTotals } from "@/lib/efactura-totals";

export async function issueInvoice(_previous: { problems: string[] }, form: FormData) {
  // parse with zod in a real app; totals from the browser are for display only
  const lines = JSON.parse(String(form.get("lines") ?? "[]")) as InvoiceLine[];
  const discount = JSON.parse(String(form.get("discount") || "null"));
  const totals = toEFacturaTotals(lines, discount);
  const problems = preflight(totals);
  if (problems.length > 0) return { problems };
  // build the UBL from `totals`, store it with the invoice number, then upload it to SPV
  return { problems: [] };
}

The whole screen around it, with a client picker and CUI lookup, the series and number, due dates, an A4 preview and the e-Factura switch, is the Invoice Page block. Its onIssue receives the document with lines and documentDiscount, the two inputs toEFacturaTotals needs.

What changes for EUR invoices and 0% lines?

The invoice can be in euros; its VAT must also exist in lei. Article 319 (23) of the Fiscal Code lets the amounts use any currency as long as the VAT is expressed in lei at the exchange rate of article 290. In the XML, rule BR-RO-030 sets the VAT accounting currency (BT-6) to RON on any non-RON invoice, and BR-53 then requires the VAT total in that currency (BT-111). The Invoice Page shows the RON equivalent of a EUR total at the BNR rate; compute BT-111 on the server from the same per-rate VAT.

The 0% rows need more than a zero:

Exempt (E): an exemption reason code or text on the breakdown row (BR-E-10), and a VAT of 0 (BR-E-09).
Reverse charge (AE): the reason "Reverse charge" (BR-AE-10), a VAT of 0 (BR-AE-09), the seller's VAT id and the buyer's VAT id or registration number (BR-AE-02).
Intra-community (K): the reason "Intra-community supply" (BR-IC-10) and the VAT ids of the seller and the buyer (BR-IC-02).

The ids those rules ask for have their own guides: Romanian CUI validation for a company's tax and VAT id, the Romanian CNP validator for B2C buyers (e-Factura accepts 13 zeros when the buyer gives none), and IBAN validation in JavaScript for the account you print under payment terms.

Should I copy this code or install the components?

Copy the math. vat-per-rate.ts has no imports and the preflight needs only its vatCents and one type, so both paste into any TypeScript project; efactura-totals.ts builds on computeInvoiceTotals from the invoicing lib and two types from the line editor. If you want React invoice line items that already show VAT per rate, the editor above installs with npx wingo-ui@latest add invoice-line-items and brings the invoicing lib and Currency Input with it. All three, and the Invoice Page, are part of Wingo UI Pro.

For the rest of an admin app around this form, the Next.js admin dashboard tutorial builds the shell, tables and settings, and more step-by-step React builds live in the Build it category.

Components in this post

Invoice line items (Pro): The lines of an invoice, quote or order edited like a small spreadsheet, with VAT per rate computed the way e-Factura checks it. Install: npx wingo-ui@latest add invoice-line-items
Invoicing (Pro): Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP. Install: npx wingo-ui@latest add invoicing
Invoice Page (Pro): An invoice editor and viewer for Romanian B2B: client, series, dates, VAT lines, totals, an A4 preview, sending and e-Factura status. Install: npx wingo-ui@latest add invoice-page
Currency Input (Pro): A money field formatted per locale as you type, with the symbol on the right side, an optional currency selector and quick amounts. Install: npx wingo-ui@latest add currency-input

FAQ

What are the VAT rates in Romania in 2026?

21% standard and 11% reduced, both in force since August 1, 2025 under Law 141/2025 and article 291 of the Fiscal Code. Before that date the standard rate was 19% and the reduced rates were 9% and 5%; a transitional 9% for some housing, extended by Law 161/2026, ended with deliveries on September 30, 2026. Exempt, reverse charge and intra-community lines go on an e-Factura invoice at 0% with the category codes E, AE and K.

Is e-Factura VAT calculated per line or per rate?

Per rate. Rule BR-CO-17 defines the VAT of each rate as the rate's taxable amount times the rate, rounded to two decimals, and article 319 (20) of the Fiscal Code asks for the VAT amount in lei for each rate. VAT shown on a line is informative and never feeds the totals.

Why does ANAF reject my e-Factura with BR-CO-14 or BR-CO-15?

Both rules compare sums to the cent. BR-CO-14 needs the invoice VAT total to equal the sum of the VAT per rate, and BR-CO-15 needs the total with VAT to equal the total without VAT plus that VAT. They fail when one total comes from rounded line amounts and another from the per-rate breakdown.

Does e-Factura accept a one-cent difference in VAT?

For the VAT of a rate, yes: in the ro16931-ubl 1.0.9 validation package, BR-CO-17 accepts a value less than one currency unit away from base times rate. The rules that add amounts up (BR-CO-10, BR-CO-11, BR-CO-13, BR-CO-14 and BR-CO-15) have no tolerance at all.

Which VAT rate applies when a July 2025 delivery is invoiced in August 2025?

Generally the rate in force when the chargeable event happened, which for a delivery is the delivery date, per article 291 (4) of the Fiscal Code. That makes it 19% for a July 2025 delivery, with exceptions for advances and invoices issued before the delivery.

This article was originally published on the Wingo UI blog: E-Factura VAT Calculation in TypeScript and React. The original has the live, interactive demos and is kept up to date.

IBAN Validation JavaScript: Mod 97, Regex and a React Field

Serban Dan Rusu — Wed, 04 Nov 2026 07:00:00 +0000

TL;DR

To validate an IBAN in JavaScript, remove the spaces, uppercase it, check the length for its country, move the first four characters to the end, turn each letter into two digits (A is 10, Z is 35) and check that the whole number mod 97 equals 1. Carry the remainder one character at a time, because the number is longer than a JavaScript Number can hold exactly. A passing IBAN is well formed, which does not prove that the account exists.

Your payout settings, supplier form or invoice template asks for a bank account, and people paste IBANs in every shape: lowercase, grouped by four, with dashes, with the non-breaking spaces a PDF adds, sometimes with "IBAN:" in front. Many IBAN validation JavaScript snippets stop at a regex, which accepts a mistyped digit, or call parseInt, which rejects valid accounts. This tutorial writes the mod 97 check in TypeScript, wires it into a zod rule and a React field that formats as you type, reads the bank out of Romanian IBANs and displays the result with a copy button. The UI uses Masked Input (Pro), Input and Copy Button (both free) from Wingo UI, the library we build, so we are not neutral. The validator is plain TypeScript you can paste anywhere.

Why is a regex not enough to validate an IBAN?

A regex checks the shape, and a typo keeps the shape. The usual IBAN validation regex, run after you remove the spaces and uppercase, is this:

const IBAN_SHAPE = /^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/;

Two letters for the country, two check digits, then 11 to 30 letters or digits, because IBANs run from 15 characters (Norway) to a maximum of 34. A country pattern is stricter: Romania's is ^RO\d{2}[A-Z]{4}[A-Z0-9]{16}$. Both accept RO49AAAA1B31007593840001, which is the sample Romanian IBAN from the IBAN registry with its last digit changed.

The two check digits exist to catch exactly that. Any string in the Romanian shape passes the regex, while only about 1 in 97 random ones passes mod 97: in a run of 200,000 random strings, about 1% did. Keep the regex anyway, as the first of three checks, so your message can say "this is not an IBAN" before it says "this IBAN has a typo".

How does the IBAN mod 97 check work?

Move the first four characters to the end, replace each letter with two digits (A is 10, B is 11, up to Z at 35), read the result as one integer and divide it by 97. A valid IBAN leaves a remainder of 1. The IBAN article on Wikipedia describes these steps from ISO 13616. Whoever issues the IBAN computes the check digits as 98 minus the remainder of the same number with 00 in their place, which is why a valid IBAN lands on 1.

Here is the UK sample IBAN worked by hand:

Step	Value
Remove the spaces	GB29NWBK60161331926819
Move the first four characters to the end	NWBK60161331926819GB29
Letters to numbers (N 23, W 32, B 11, K 20, G 16)	2332112060161331926819161129
Remainder mod 97	1

That integer has 28 digits, and a JavaScript Number is exact only up to 2^53, which has 16 digits. Number(digits) % 97 and parseInt(digits, 10) % 97 both return 5 for this IBAN, so they reject a valid account. BigInt(digits) % 97n works. Carrying the remainder one character at a time works too, and it skips the conversion to a digit string.

Wikipedia says the check detects all single substitution errors and all or nearly all swaps of neighboring characters. We tested that. On 2,000 random German IBANs, which are all digits after the country code, every single-digit change and every swap of two neighbors failed the check. Letters weaken it: on 2,000 random Romanian-style IBANs with letters in the account part, about 0.35% of single-character changes and of neighbor swaps still passed, roughly 1 in 300, because a letter becomes two digits. Swap the 1B in the registry sample to B1 and both read 111, so RO49AAAAB131007593840000 passes.

How do I validate an IBAN in TypeScript?

To validate IBAN numbers, normalize the input, then run three checks in order: the shape, the length for the country, and mod 97. Returning which check failed lets the form explain the problem instead of saying "invalid":

// lib/iban.ts
// the 42 IBAN country codes in the SEPA schemes (EPC, August 2026), with their
// lengths from SWIFT's IBAN Registry as ibantools 4.5.4 ships them
const LENGTHS: Record<string, number> = Object.fromEntries(
  (
    "AD24 AL28 AT20 BE16 BG22 CH21 CY28 CZ24 DE22 DK18 EE20 ES24 FI18 FR27 " +
    "GB22 GI23 GR27 HR21 HU28 IE22 IS26 IT27 LI21 LT20 LU20 LV21 MC27 MD24 " +
    "ME22 MK19 MT31 NL18 NO15 PL28 PT25 RO24 RS22 SE24 SI19 SK24 SM27 VA22"
  )
    .split(" ")
    .map((entry) => [entry.slice(0, 2), Number(entry.slice(2))]),
);

export type IbanProblem = "format" | "country" | "length" | "checksum";

export const ibanLength = (country: string) => LENGTHS[country.toUpperCase()];

// " iban: ro49 aaaa-1b31 ..." -> "RO49AAAA1B31..."; \s also covers the non-breaking spaces PDFs paste
export function electronicIban(input: string): string {
  return input.trim().toUpperCase().replace(/^IBAN:?/, "").replace(/[\s.-]/g, "");
}

// the remainder of the rearranged IBAN, one character at a time, so the number never outgrows a float
function mod97(iban: string): number {
  const rearranged = iban.slice(4) + iban.slice(0, 4);
  let remainder = 0;
  for (const char of rearranged) {
    // A is 10 ... Z is 35: a letter adds two digits, so shift by 100
    const value = char >= "A" ? char.charCodeAt(0) - 55 : Number(char);
    remainder = (remainder * (value > 9 ? 100 : 10) + value) % 97;
  }
  return remainder;
}

export function checkIban(input: string): { iban: string; problem: IbanProblem | null } {
  const iban = electronicIban(input);
  if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban)) return { iban, problem: "format" };
  const length = ibanLength(iban.slice(0, 2));
  if (!length) return { iban, problem: "country" };
  if (iban.length !== length) return { iban, problem: "length" };
  return { iban, problem: mod97(iban) === 1 ? null : "checksum" };
}

export const isValidIban = (input: string) => checkIban(input).problem === null;

// "RO49AAAA1B31007593840000" -> "RO49 AAAA 1B31 0075 9384 0000"
export const formatIban = (input: string) => electronicIban(input).replace(/(.{4})(?=.)/g, "$1 ");

// check digits for test data: ibanCheckDigits("GB", "NWBK60161331926819") -> "29"
export function ibanCheckDigits(country: string, bban: string): string {
  return String(98 - mod97(`${country}00${bban}`)).padStart(2, "0");
}

checkIban("gb29-nwbk-6016-1331-9268-19"); // { iban: "GB29NWBK60161331926819", problem: null }
checkIban("IBAN: RO49 AAAA 1B31 0075 9384 0001"); // problem: "checksum"
checkIban("US12345678901234567"); // problem: "country"
formatIban("ro49aaaa1b31007593840000"); // "RO49 AAAA 1B31 0075 9384 0000"
ibanCheckDigits("RO", "BTRL0123456789ABCDEF"); // "17", so RO17BTRL0123456789ABCDEF passes

Four decisions in that file are worth copying even if you rewrite the rest:

Uppercase first. "n".charCodeAt(0) - 55 is 55, where "N" gives 23, so a lowercase IBAN fails without it.
Strip every kind of space. \s in a JavaScript regex also matches the non-breaking and narrow spaces that PDFs and bank apps put between the groups.
Reject countries you do not pay. The table holds the 42 IBAN country codes in the EPC's August 2026 overview of SEPA scheme participants, Albania, Moldova, Montenegro, North Macedonia and Serbia included, so anything else gets "country", the honest answer for a SEPA payout form. If you accept IBANs from every country, use a library (see the last section).
Generate test data. ibanCheckDigits builds a valid IBAN from any country and account part, so your fixtures never hold a real person's account.

What is the Romanian IBAN format?

A Romanian IBAN has 24 characters: RO, two check digits, four letters for the bank, and 16 letters or digits for the branch and the account. The four bank letters are the first four characters of the bank's BIC, its SWIFT code, so BTRL is Banca Transilvania (BIC BTRLRO22). Wikipedia's IBAN formats by country table writes it as RO kk bbbb cccc cccc cccc cccc.

Positions	Registry sample	Meaning
1 to 2	RO	Country
3 to 4	49	Check digits
5 to 8	AAAA	Bank, the first four characters of its BIC
9 to 24	1B31 0075 9384 0000	Branch and account, letters allowed

Two rules follow. A "digits only after the bank code" rule rejects real Romanian accounts, since the account part may hold letters: Banca Transilvania IBANs, for one, carry letters such as RONCRT right after the bank code. And the bank is one lookup away:

// lib/iban.ts (continued)
// the four letters after the check digits are the start of the bank's BIC
const RO_BANKS: Record<string, string> = {
  BTRL: "Banca Transilvania",
  RNCB: "BCR",
  BRDE: "BRD",
  INGB: "ING Bank",
  RZBR: "Raiffeisen Bank",
  BACX: "UniCredit Bank",
  CECE: "CEC Bank",
  TREZ: "State Treasury",
};

export function romanianBank(input: string): string | null {
  const iban = electronicIban(input);
  return iban.startsWith("RO") ? (RO_BANKS[iban.slice(4, 8)] ?? null) : null;
}

romanianBank("RO17 BTRL 0123 4567 89AB CDEF"); // "Banca Transilvania"
romanianBank("GB29 NWBK 6016 1331 9268 19"); // null

Show the name as a hint the person can recognize. It proves nothing about the account, and the map is a snapshot of banks that merge: when OTP Bank Romania merged into Banca Transilvania in early 2025, its customers received new BTRL IBANs, and Banca Transilvania sent employers the new IBANs for salaries paid from March 2025. An old OTP IBAN still passes mod 97.

How do I build an IBAN field that formats as you type?

Use a masked field that keeps the raw value apart from what it displays. The iban preset of Masked Input uppercases as you type, groups by four, keeps the caret right after the character you typed and cleans separators out of a paste. Once the IBAN is complete it runs mod 97 and pops in a check or an alert icon; the red ring and aria-invalid wait until you leave the field. On phones it keeps the text keyboard with autoCapitalize="characters", because a numeric keypad has no letters for the country code.

Live demo: Masked Input. The original article embeds an interactive demo here (Type or paste gb29-nwbk-6016-1331-9268-19: the field uppercases it, groups it by four and shows a check. Change the last digit and the check turns into an alert). Try it live on wingo-ui.com or open the Masked Input docs. Install: npx wingo-ui@latest add masked-input

The preset ships lengths for nine countries: Romania, Moldova, Germany, the UK, France, Italy, Spain, Bulgaria and Hungary. For any other country it still groups by four but waits for 34 characters before it checks, so a Dutch IBAN never gets its icon. Pass a mask sized from the same table as your validator. The preset keeps its uppercasing and its keyboard settings:

// lib/iban-mask.ts
import { ibanLength } from "@/lib/iban";

// "AA99 **** **** ..." sized to the country, so the field knows when the IBAN is complete
export function ibanMask(raw: string): string {
  const length = ibanLength(raw.slice(0, 2)) ?? 34;
  let mask = "AA99";
  for (let i = 4; i < length; i++) mask += (i % 4 === 0 ? " " : "") + "*";
  return mask;
}

The zod rule turns each failed check into its own message and hands your database the electronic format, without spaces:

// lib/iban-schema.ts
import { z } from "zod";
import { checkIban, electronicIban, type IbanProblem } from "@/lib/iban";

const MESSAGES: Record<IbanProblem, string> = {
  format: "Enter the full IBAN, starting with the country code, like GB29 NWBK 6016 1331 9268 19",
  country: "We can only pay out to banks in SEPA countries",
  length: "This IBAN is too short or too long for its country",
  checksum: "This IBAN has a typo: the check digits do not match",
};

export const iban = z
  .string()
  .trim()
  .min(1, { error: "Enter your IBAN", abort: true })
  .check((ctx) => {
    const { problem } = checkIban(ctx.value);
    if (problem) ctx.issues.push({ code: "custom", message: MESSAGES[problem], input: ctx.value });
  })
  .transform(electronicIban);

Wire it with React Hook Form's Controller, because the input element holds the masked text and onValueChange hands you the raw value. Passing validate={isValidIban} makes the field's icon and the zod rule agree on every IBAN:

"use client";

import { Controller, useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { MaskedInput } from "@/components/ui/masked-input";
import { electronicIban, isValidIban, romanianBank } from "@/lib/iban";
import { ibanMask } from "@/lib/iban-mask";
import { iban } from "@/lib/iban-schema";

const schema = z.object({
  holder: z.string().trim().min(1, { error: "Enter the account holder's name" }),
  iban,
});

type Values = z.output<typeof schema>;

export function PayoutForm({ onSave }: { onSave: (values: Values) => Promise<void> }) {
  const form = useForm<z.input<typeof schema>, unknown, Values>({
    resolver: zodResolver(schema),
    // the first error waits for blur, then the field re-checks on every keystroke
    mode: "onTouched",
    defaultValues: { holder: "", iban: "" },
  });
  const { errors, isSubmitting } = form.formState;

  return (
    <form noValidate onSubmit={form.handleSubmit(onSave)} className="flex flex-col gap-4">
      <Input label="Account holder" autoComplete="name" {...form.register("holder")} error={errors.holder?.message} />
      <Controller
        control={form.control}
        name="iban"
        render={({ field, fieldState }) => (
          <MaskedInput
            preset="iban"
            mask={ibanMask}
            validate={isValidIban}
            label="IBAN"
            placeholder="GB29 NWBK 6016 1331 9268 19"
            ref={field.ref}
            value={field.value}
            onValueChange={(raw) => field.onChange(raw)}
            onBlur={field.onBlur}
            // the mask keeps letters, so a pasted "IBAN:" label would become the country code
            onPaste={(event) => {
              const text = event.clipboardData.getData("text");
              if (!/^\s*iban\b/i.test(text)) return;
              event.preventDefault();
              field.onChange(electronicIban(text));
            }}
            // a romanian IBAN names its bank as soon as the bank code is in
            description={romanianBank(field.value) ?? "Paste it with or without spaces."}
            error={fieldState.error?.message}
          />
        )}
      />
      <Button type="submit" loading={isSubmitting}>
        Save payout details
      </Button>
    </form>
  );
}

The description reads "Banca Transilvania" as soon as someone types RO17BTRL, a quick way for them to confirm they copied the account they meant. The onPaste handler covers the one paste the mask cannot clean up. The field drops every separator but keeps letters, so "IBAN: RO17 BTRL ..." copied from a statement would turn into IB17 BTRL ... and fail with the country message. The handler strips the label with electronicIban before the mask sees it.

If you would rather not write the rule, the Pro form-validation lib has createValidators().iban(), with one message for any failure and no country limit.

How do I show an IBAN so people can copy it?

Display it in groups of four and copy it without spaces. The groups help people read it aloud or compare it with a paper invoice. The clipboard should get the electronic format, because a 34-character IBAN grows to 42 characters with spaces, and a bank form with maxLength={34} cuts the end off on paste.

import { CopyButton } from "@/components/ui/copy-button";
import { electronicIban, formatIban, romanianBank } from "@/lib/iban";

export function PayoutAccount({ iban }: { iban: string }) {
  const bank = romanianBank(iban);
  return (
    <div className="flex items-center justify-between gap-3 rounded-2xl bg-surface p-4">
      <div className="min-w-0">
        <p className="font-mono text-sm">{formatIban(iban)}</p>
        {bank && <p className="text-xs text-muted-foreground">{bank}</p>}
      </div>
      <CopyButton value={electronicIban(iban)} copyLabel="Copy IBAN" />
    </div>
  );
}

Copy Button renders an icon button labeled "Copy IBAN". On desktop its tooltip switches to "Copied"; on a phone the check, a short vibration and a screen reader announcement carry the feedback, and the small size keeps a 44px hit area on touch. The grouped IBAN wraps at its spaces, so it never pushes the row wider than a 360px screen.

Does a valid IBAN mean the account exists?

No. The check digits prove that the IBAN is well formed. A closed account, an account at a bank that has since merged and the wrong person's account all pass. The account holder's name is what catches the last case. Under the EU Instant Payments Regulation, banks must offer Verification of Payee, which compares the payee's name with the account before a credit transfer and returns a result such as match, close match or no match. The ECB's overview of the regulation lists October 9, 2025 for the euro area and July 9, 2027 for the non-euro member states, Romania among them.

That check runs at the payer's bank when the money leaves, long after your form was submitted. So check the digits while people type, and ask for the account holder's name next to the IBAN, as the form above does, so the bank has a name to compare.

Should I use a library like ibantools instead?

Use one when you accept IBANs from every country. As of October 2026, ibantools 4.5.4 (published April 2026, MIT or MPL-2.0) ships the length and account pattern of each registry country, validateIBAN returns error codes you can map to messages, and isValidBIC checks SWIFT codes. It also runs the national check digits some countries add inside the account part, such as Belgium, Spain and France, which the file above skips. One catch for a SEPA form: its isSEPACountry in 4.5.4 still returns false for Albania, Moldova, Montenegro, North Macedonia and Serbia. The iban package, the other common answer, was last published in February 2020. For a SEPA-only form, the file above covers the shape, the length and mod 97 without a dependency, and you can read every line of it.

Should I copy this code or install it?

Copy it when you need one plain field: lib/iban.ts, the zod rule and the free Input cover it. In Wingo UI Pro, Masked Input is the field from the demo, and the invoicing lib exports isValidIban (lengths for 19 countries, while any other country gets the shape and mod 97), formatIban, getIbanBank and a RO_BANKS map of 19 Romanian bank codes, next to the checks from our Romanian CUI validation guide and our Romanian CNP validator. The plans are on the pricing page. Install the field and the free copy button with npx wingo-ui@latest add masked-input copy-button. For the rest of the form anatomy, read React form components: accessible fields, zod and mobile, or browse more component guides.

Components in this post

Masked Input (Pro): A text field that formats itself as you type or paste: card number, expiry, CVC, IBAN, CNP, postal code or a custom mask. Install: npx wingo-ui@latest add masked-input
Invoicing (Pro): Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP. Install: npx wingo-ui@latest add invoicing
Copy Button (Free): Copy an IBAN, a tax ID, a link or an API key with one tap: an icon button with a tooltip, a labelled button, and CopyText for inline values. Install: npx wingo-ui@latest add copy-button
Input (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: npx wingo-ui@latest add input
Form validation (Pro): Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks. Install: npx wingo-ui@latest add form-validation

FAQ

How do I validate an IBAN in JavaScript?

Remove spaces and dashes, uppercase the string and check its length for the country. Then move the first four characters to the end, replace each letter with its number (A is 10, Z is 35) and compute the remainder mod 97 one digit at a time; the IBAN is valid when the remainder is 1.

What is the regex for an IBAN?

After you remove the spaces and uppercase, /^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/ matches the shape of any IBAN, and a country pattern such as ^RO\d{2}[A-Z]{4}[A-Z0-9]{16}$ adds the length. Neither one tests the check digits, so run mod 97 after the regex.

How many characters is a Romanian IBAN?

24: RO, two check digits, four letters for the bank (the first four characters of its BIC) and 16 letters or digits for the branch and the account, for example RO49 AAAA 1B31 0075 9384 0000.

Does a valid IBAN mean the bank account exists?

No. The check digits only prove that the IBAN is well formed, so a closed account or the wrong person's account still passes. In the EU, Verification of Payee at the payer's bank compares the payee's name with the account before a transfer, from October 9, 2025 in the euro area and from July 9, 2027 in Romania and the other non-euro member states.

Why does my IBAN check reject valid IBANs?

Often it is Number or parseInt: the rearranged IBAN has more digits than a JavaScript Number holds exactly, so the remainder comes out wrong. Lowercase letters, non-breaking spaces pasted from a PDF and an IBAN: label in front are the other usual suspects.

How do I find the bank from a Romanian IBAN?

Read characters 5 to 8. They are the first four characters of the bank's BIC, so BTRL is Banca Transilvania and RNCB is BCR. Keep your map current, because merged banks leave old codes behind.

This article was originally published on the Wingo UI blog: IBAN Validation JavaScript: Mod 97, Regex and a React Field. The original has the live, interactive demos and is kept up to date.

Web Vibration API: Haptic Feedback on Android and iPhone

Serban Dan Rusu — Tue, 03 Nov 2026 15:00:00 +0000

TL;DR

As of October 2026 the Web Vibration API (navigator.vibrate) works only in Chromium browsers on Android, only after the user has tapped the page, and with no control over intensity; Safari on iPhone has never shipped it. The one haptic a page can trigger on an iPhone is the system tick of a native HTML switch, and since iOS 26.5 WebKit plays it only when the user's own tap toggles the switch, never for a click from JavaScript. Put navigator.vibrate behind one helper that returns false instead of throwing, lay a label for a hidden switch over buttons that should tick on iPhone, and never let a tick be the only feedback.

You want a tap to tick under the thumb the way it does in a native app, so you reach for the web vibration API. On an Android phone navigator.vibrate(10) works on the first try. On an iPhone nothing happens, on a laptop the call returns true and nothing happens, and the iPhone workaround you found on GitHub stopped working in iOS 26.5. This tutorial maps what a page can really trigger in October 2026, builds a helper that stays silent wherever it cannot play, and wires haptics into a switch, a button and a wheel picker in React.

What can the Web Vibration API do in 2026?

It can switch the vibration motor on and off for durations you give in milliseconds, in Chromium browsers on Android, after the user has tapped the page. That is the whole API: one method, navigator.vibrate, that takes a number or an array of alternating vibrate and pause times. There is no intensity, no waveform and no way to ask whether the device has a motor at all. Software Mansion's August 2026 overview of web haptics sums up the support in one line: "the vibration API is effectively limited to Chromium-based browsers."

Here is where a tick can reach a finger, as of October 2026 (caniuse for support, our own test in desktop Chromium for the last row):

Where the page runs	`navigator.vibrate`	What the user feels
Chrome or Samsung Internet on Android	supported	the pattern you pass, once the page has seen a tap
Firefox	removed in version 129, not supported on Android	nothing
Safari on iPhone, and home screen web apps	never shipped	the system tick of a native switch, only when the user's own tap toggles it
Chrome on a desktop	present, returns `true`	nothing, there is no motor

The last row is the trap. Feature detection with "vibrate" in navigator says yes in desktop Chrome, so it tells you nothing about hardware. The boolean that navigator.vibrate() returns only says the browser accepted the pattern; it says nothing about whether anyone felt it.

How does navigator.vibrate behave on Android?

It plays the pattern you pass and replaces any pattern already running, within limits you can read in Chromium's vibration controller:

navigator.vibrate(8); // one 8ms pulse: a light tick
navigator.vibrate([10, 60, 16]); // pulse, pause, pulse: a success pattern
navigator.vibrate(0); // cancels whatever is running (so does [])

It needs a tap first. MDN lists sticky user activation as a requirement. Until the page has seen a tap, a click or a key press, Chrome returns false and logs "Blocked call to navigator.vibrate because user hasn't tapped on the frame or any embedded frame yet". Once granted, the activation lasts until the page navigates, so a tick from a scroll handler or after an await works later on.
It is silent in the background. The call returns false while the page is hidden.
Long patterns are trimmed. Chromium caps each entry at 10,000ms, keeps the first 99 entries and drops a trailing pause.
The phone can overrule you. MDN notes that some devices do not vibrate in silent or Do Not Disturb mode.

Keep the pulses short; the helper below uses 4 to 22ms per pulse. The 200ms buzz in many examples (MDN's first one included) reads as a notification, which is the wrong message for a toggle.

Does the Web Vibration API work on iOS?

No. Safari has never implemented navigator.vibrate, and caniuse lists no version of Safari on iOS with it, up to 27.2. Look up web vibration API iOS support and you land on one workaround: Safari 17.4 added a native switch control, <input type="checkbox" switch> (WebKit's announcement), and toggling it plays the system haptic tick.

Until iOS 26.5, libraries such as ios-haptics played that tick on demand by calling .click() on a hidden label wired to the switch. That no longer works. The ios-haptics README of April 2026 says the trick "only works on ios 17.4 to 26.4, as apple patched it in ios 26.5". The WebKit fix, merged into the main branch on May 21, 2026, closes that gap: WebKit already required user activation for the haptic, and now it also requires a trusted event, which a click forwarded from label.click() no longer is.

What still works is a real tap that lands on a label for the switch. The tap produces a trusted click, the label forwards it to the switch, and because the original click was trusted, the WebKit change still lets the switch tick. The ios-haptics source moved to exactly that on September 22, 2026: it lays a transparent label over your element. Here is the same idea as a React 19 component:

// components/ios-tap-tick.tsx
"use client";

// iOS plays the switch haptic only for a trusted click, so the user's own tap has to land on a label for the switch.
// put it inside a positioned button; it covers the button and the click still bubbles to the button's onClick
export function IOSTapTick() {
  return (
    <label
      aria-hidden="true"
      data-slot="ios-tap-tick"
      className="absolute inset-0 touch-manipulation [-webkit-tap-highlight-color:transparent]"
    >
      <input
        type="checkbox"
        // react 19 passes the unknown attribute through; the spread keeps TypeScript quiet
        {...{ switch: "" }}
        tabIndex={-1}
        // the label, not the switch, sits under the finger, so a swipe that starts here still scrolls the page
        className="invisible absolute m-0 size-px"
        // the label forwards the click to the switch: stop that second click before it reaches the button
        onClick={(event) => event.stopPropagation()}
      />
    </label>
  );
}

Use it in buttons, not links: in our Chromium test a label inside an <a> ran the link's onClick but took over the default action, so the link never navigated. Leave the input without a name, so it never ends up in a form submission. Outside iOS a tap on it only toggles a hidden checkbox nobody sees, so it can render on every platform and never causes a hydration mismatch.

On an iPhone you get one fixed tick per tap, from the tap itself: no patterns, nothing after an await, nothing during a drag, and nothing for a wheel spinning past rows, because a scroll never produces a click.

How do you call navigator.vibrate safely where it is unsupported?

Check for the method itself, check activation, catch everything, and return a boolean. Here is the whole helper without dependencies:

// lib/vibrate.ts
export type HapticKind = "selection" | "light" | "medium" | "heavy" | "success" | "warning" | "error";

const PATTERNS: Record<HapticKind, number | number[]> = {
  selection: 4,
  light: 8,
  medium: 14,
  heavy: 22,
  success: [10, 60, 16],
  warning: [16, 70, 16],
  error: [22, 50, 22, 50, 22],
};

let enabled = true;

export function setHapticsEnabled(value: boolean) {
  enabled = value;
}

export function vibrate(kind: HapticKind = "light"): boolean {
  if (!enabled) return false;
  // node 21+ has a global navigator too, so test for the method, not for navigator
  if (typeof navigator === "undefined" || typeof navigator.vibrate !== "function") return false;
  // chrome blocks the call (and logs a warning) until the page has seen a tap
  if (navigator.userActivation && !navigator.userActivation.hasBeenActive) return false;
  try {
    return navigator.vibrate(PATTERNS[kind]);
  } catch {
    return false; // feedback is never worth an exception
  }
}

The Node check matters. Node 21 and later define a global navigator with no vibrate, so a helper that only checks typeof navigator gets past its guard on the server and calls a method that is not there.

Wingo UI's haptics helper is the same idea plus an iPhone fallback and a force option that plays a tick even when haptics are off. haptic(kind) returns whether a haptic was sent, configureHaptics({ enabled, iosFallback }) sets the app-wide options, and supportsHaptics() tells you whether the browser exposes a haptic path at all (call it in an effect: it is false on the server, and true in desktop Chrome for the reason above).

Live demo: Haptics. The original article embeds an interactive demo here (On an Android phone, tap each tile to feel the seven kinds; the bars draw each vibration pattern and the line under the card shows what haptic() returned). Try it live on wingo-ui.com or open the Haptics docs. Install: npx wingo-ui@latest add haptics

A caveat about our own code: the helper's iosFallback option, on by default, still clicks a hidden label from script. That plays on iPhones up to iOS 26.4, is ignored from 26.5, and the call still returns true there because WebKit reports nothing back. If you add the tap overlay above, call configureHaptics({ iosFallback: false }) once so iPhones on older versions do not tick twice.

The snippets below import Wingo UI's helper. With the dependency-free file above, import vibrate from @/lib/vibrate instead and use setHapticsEnabled in place of configureHaptics; it has no force option.

Which haptic should each interaction get?

One tick per event, sized to the event. These are the patterns the helper sends on Android:

Kind	Pattern (ms)	Use it for	Wingo UI component that plays it
`selection`	4	a row of a wheel or a slider step passing the center	Picker Wheel
`light`	8	a tap, a toggle	Haptic Button press
`medium`	14	a long press, a snap, a crossed threshold	Haptic Button long press, Pull To Refresh arming, Slide To Confirm armed
`heavy`	22	a committed full swipe, a drop	none; call it from your own drop handler
`success`	10, 60, 16	payment sent, item saved	Haptic Button hold confirmed, Slide To Confirm done
`warning`	16, 70, 16	a limit reached, a hold released too early	Haptic Button tap in hold mode
`error`	22, 50, 22, 50, 22	a wrong PIN, a failed save	Haptic Button rejected promise

Three rules keep it from turning into noise. Call it from the handler of a real gesture, never from an effect or a render. Never tick per animation frame; tick when something changes state, like a row reaching the center. And never put information only in the tick: desktop users, iPhone users on a wheel and anyone with a phone on silent will not feel it, so the screen must say the same thing.

How do you add React haptic feedback to a switch, a button and a wheel?

Call haptic() in the handler where the state changes, once per change.

A switch

The free Switch calls onCheckedChange on every click, key or drag, and a returned promise makes it spin, then flip back with errorText if the save fails. Tick on the change and again on failure:

"use client";

import { Switch } from "@/components/ui/switch";
import { haptic } from "@/lib/haptics";

export function NewMessagesSetting({ save }: { save: (on: boolean) => Promise<void> }) {
  return (
    <Switch
      label="New messages"
      description="When someone writes to you about a listing"
      labelPosition="start"
      defaultChecked
      onCheckedChange={async (on) => {
        haptic("light");
        try {
          await save(on);
        } catch (error) {
          haptic("error");
          throw error; // the switch flips back and shows errorText
        }
      }}
    />
  );
}

On iOS 26.5 and later this Switch stays silent: it is a Radix button with role="switch", not the native input, so no system tick comes with the tap, and haptic() cannot reach the switch tick from script. If an iPhone tick on a settings toggle matters more to you than the custom look, a plain <input type="checkbox" switch> ticks on its own and renders as a checkbox in browsers that do not know the attribute.

A button

The Haptic Button plays its hapticKind (default light) on touch and pen presses only, so a mouse click never asks for a vibration. In mode="hold" it plays light when the hold starts, success once onConfirm has finished, warning for a tap that was too short and error when onConfirm rejects; with onLongPress set, a long press plays medium.

"use client";

import { Send } from "lucide-react";
import { HapticButton } from "@/components/ui/haptic-button";

export function SendRent({ onSend }: { onSend: () => Promise<void> }) {
  return (
    <HapticButton mode="hold" fullWidth leftIcon={<Send />} labels={{ holdHint: "Hold to send" }} onConfirm={onSend}>
      Hold to send $1,850
    </HapticButton>
  );
}

Live demo: Haptic Button. The original article embeds an interactive demo here (Hold the Hold to send button with a finger on an Android phone: a light tick starts the fill, a success pattern lands with the check, and a quick tap shakes the button with a warning tick). Try it live on wingo-ui.com or open the Haptic Button docs. Install: npx wingo-ui@latest add haptic-button

For an ordinary Button that should tick on both platforms, combine the call and the overlay. The Button is already position: relative, so the overlay covers it:

"use client";

import { Button } from "@/components/ui/button";
import { IOSTapTick } from "@/components/ios-tap-tick";
import { haptic } from "@/lib/haptics";

export function SaveButton({ onSave }: { onSave: () => Promise<void> }) {
  return (
    <Button
      onClick={async () => {
        haptic("light"); // android; the overlay ticks on iPhone
        try {
          await onSave();
          haptic("success"); // android only: iPhone has no tick after an await
        } catch {
          haptic("error");
        }
      }}
    >
      Save
      <IOSTapTick />
    </Button>
  );
}

A wheel

The Picker Wheel plays a selection tick each time a new row reaches the center while a finger, a mouse drag or a scroll wheel drives it, and never for keys, clicks or value changes from outside. haptics={false} turns it off.

"use client";

import { PickerWheel, pickerRange } from "@/components/ui/picker-wheel";

const hours = pickerRange(8, 19, { pad: 2 });
const minutes = pickerRange(0, 55, { step: 5, pad: 2 });

export function AppointmentTime() {
  return (
    <PickerWheel
      aria-label="Appointment time"
      loop
      defaultValue={["10", "30"]}
      columns={[
        { id: "hour", label: "h", options: hours },
        { id: "minute", label: "min", options: minutes },
      ]}
    />
  );
}

Live demo: Picker Wheel. The original article embeds an interactive demo here (Flick a column on an Android phone: each row that reaches the center ticks once, and the value changes when the wheel comes to rest). Try it live on wingo-ui.com or open the Picker Wheel docs. Install: npx wingo-ui@latest add picker-wheel

This is the clearest case of the platform gap. On Android every row that passes the center ticks. On an iPhone the wheel is silent from iOS 26.5, because a spin is a scroll and never produces the trusted click the switch needs; the band, the tilt and the snap carry the feedback there.

How do you let people turn haptics off?

Give them a setting and pass it to the helper once. Every haptic feedback web app needs one: some people find vibration distracting, and the browser gives a page no way to read the phone's own haptics setting.

"use client";

import { useEffect, useState } from "react";
import { Switch } from "@/components/ui/switch";
import { configureHaptics, haptic } from "@/lib/haptics";

export function VibrationSetting() {
  const [on, setOn] = useState(true);

  useEffect(() => {
    configureHaptics({ enabled: on });
  }, [on]);

  return (
    <Switch
      label="Vibrations"
      description="A short tick when you tap, hold or pick"
      labelPosition="start"
      checked={on}
      onCheckedChange={(next) => {
        setOn(next);
        // the effect has not run yet, so force the confirmation tick
        if (next) haptic("light", { force: true });
      }}
    />
  );
}

Store the value with the rest of the user's settings. Every component that ticks through the helper follows it without a prop: the Haptic Button, the Picker Wheel, and the Pull To Refresh from our pull to refresh guide among them.

What comes after navigator.vibrate?

A semantic API with named effects, if browsers adopt the one being drafted now. The Web Haptics API started as a proposal to the CSS Working Group in March 2026 and has been incubated at the WICG since April. Its draft has a navigator.playHaptics(effect, intensity) call and a nested @haptic CSS rule, with six named effects (hint, edge, tick, align, success, error) and an intensity from 0 to 1 that the browser maps to the platform's own haptics. The call returns undefined, so a page learns nothing about the device. As of October 2026 Chrome Platform Status lists Web haptics as Proposed, and no stable browser ships it.

The shape is familiar: named kinds instead of millisecond patterns. If your app already funnels every tick through one haptic(kind) call, moving to a new API later means changing one file.

Where should you start?

Add a helper first, then tick the three places users touch most: toggles, the primary button and any wheel or slider. The dependency-free lib/vibrate.ts above covers Android. npx wingo-ui@latest add haptics copies Wingo UI's lib/haptics.ts instead; it is part of Wingo UI Pro, like the Haptic Button and the Picker Wheel, while the Switch is free. For the rest of the phone checklist (bottom sheets, 44px touch targets, safe area insets), read mobile-first React components or browse the Mobile UI in React category.

Components in this post

Haptics (Pro): Haptic feedback for the web in one call: short vibration ticks on Android and the system tick on iPhone, silent everywhere else. Install: npx wingo-ui@latest add haptics
Haptic Button (Pro): A button that answers like a native control: spring press, touch ripple, a haptic tick, a long-press action and a hold-to-confirm mode. Install: npx wingo-ui@latest add haptic-button
Switch (Free): An on / off setting that applies at once: a spring thumb that stretches and drags like iOS, thumb icons, and async saves that roll back. Install: npx wingo-ui@latest add switch
Picker Wheel (Pro): The iOS wheel picker for the web: columns that spin with native momentum and click into place on a 3D cylinder, inline or as a field. Install: npx wingo-ui@latest add picker-wheel

FAQ

Does navigator.vibrate work on iPhone?

No. Safari has never implemented the Vibration API, and as of October 2026 caniuse lists no version of Safari on iOS that supports it. The only haptic a web page can produce on an iPhone is the system tick of a native switch input, and since iOS 26.5 only the user's own tap on it plays that tick.

Why does navigator.vibrate return true on my laptop?

Because true only means the browser accepted the pattern. Desktop Chrome exposes navigator.vibrate and, once the page has seen a click, returns true for a valid pattern even though there is no motor to run. Use the return value to detect refusals and never to detect hardware.

Why does navigator.vibrate do nothing on my Android phone?

The usual causes are a page the user has not tapped yet (Chrome blocks the call and logs a warning until the page has sticky user activation), a hidden tab, silent or Do Not Disturb mode, or Firefox, which removed the API in version 129.

Can a web page control vibration intensity?

Not with the Vibration API, which only switches the motor on and off for the durations you pass. The Web Haptics API proposal, incubated at the WICG since April 2026, adds named effects with an intensity from 0 to 1, but as of October 2026 no stable browser ships it.

Is the Wingo UI haptics helper free?

No. The haptics helper, the Haptic Button and the Picker Wheel are Pro items; the Switch is free. With a Pro account signed in through npx wingo-ui@latest login, npx wingo-ui@latest add haptics copies lib/haptics.ts into your project.

This article was originally published on the Wingo UI blog: Web Vibration API: Haptic Feedback on Android and iPhone. The original has the live, interactive demos and is kept up to date.

Nextjs Admin Dashboard Tutorial: 5 Screens, Phone-Ready

Serban Dan Rusu — Tue, 03 Nov 2026 07:00:00 +0000

TL;DR

Build a Next.js admin dashboard as five screens in one App Router route group: an app shell layout, a home page with KPIs, list pages with a server-side data table whose state lives in the URL, a settings page and a team page with roles. Pages fetch through a server-only data access layer, and every change goes through a Server Action that checks the session itself. On phones the sidebar becomes a drawer with a bottom tab bar, table rows become cards and menus open as bottom sheets.

Most admin dashboard tutorials stop at a sidebar, four stat cards, a chart and a table that scrolls sideways on a phone. A back office needs more: list pages that filter on the server, a settings page that keeps what someone typed when a save fails, a team page with roles, loading and error states on every route, and a layout that works when the person approving an invoice is on a phone. This nextjs admin dashboard tutorial builds all of it on the Next.js App Router with React 19 and Tailwind CSS v4, screen by screen, with the code. We build Wingo UI and the examples use our blocks, so we are not neutral; the App Router patterns work with any component library, and the last section compares the free starters.

What does a Next.js admin dashboard need?

Five screens and two states: a shell around a home page, list pages, a settings page and a team page, each with a loading and an error state. The React admin dashboard components we use for each, and their phone behavior:

Screen	Its job	Built with	On a phone
Shell	Navigation, search, the account	App Shell with Sidebar	The sidebar moves into a drawer, a tab bar takes the bottom edge
Home	What changed, what needs attention	Admin Dashboard Page or KPI Dashboard	KPIs two per row, panels in one column
Lists	Find, filter and act on records	Data Table in server mode	Rows become cards, menus become bottom sheets
Settings	Profile, account, billing, security	Settings Page	A list that pushes each section in, like iOS Settings
Team	Members, roles, audit log	Users Admin Page	Member cards, one role at a time in the matrix
Loading and errors	Every route	`loading.tsx`, `error.tsx` and each block's `loading` prop	Skeletons in the phone layout

How should you structure the App Router for an admin dashboard?

Put every admin route in one route group with its own layout. A folder in parentheses does not appear in the URL, so app/(admin)/clients/page.tsx serves /clients while the group's layout.tsx wraps it in the shell. Sign-in lives in its own group and never sees the sidebar.

app/
  layout.tsx                 root: html, body, <Providers>
  providers.tsx              LinkProvider (next/link) and the Toaster
  (auth)/
    sign-in/page.tsx         no shell
  (admin)/
    layout.tsx               the shell: AppShell, Sidebar, Topbar
    nav.tsx                  sidebar groups and phone tabs
    error.tsx                the admin error boundary
    page.tsx                 /: the home with KPIs
    dashboard-home.tsx
    actions.ts               order actions for the home
    clients/
      page.tsx               reads the URL, fetches one page
      clients-table.tsx
      query.ts
      loading.tsx
      [id]/page.tsx          one client
    settings/
      page.tsx
      settings-view.tsx
      actions.ts
    team/
      page.tsx
      team-view.tsx
      actions.ts
server/
  dal.ts                     "server-only": verifySession, getUser, requireAdmin

Three rules hold it together:

Pages fetch, views render. Each page.tsx is a server component that loads data. The blocks are client components, so function props (a save handler, a router call) live in a small *-view.tsx next to the page.
Auth lives in the data access layer. Layouts do not re-render on navigation, so a layout check misses route changes. Call verifySession() from a server-only module in every page and every Server Action; the data security guide says to treat each Server Action as reachable by a direct POST request.
The URL holds the view. Period, filters, page, open tab: if it changes what the screen shows, it goes in the search params, so a link reproduces the screen.

How do you build the app shell for a Next.js admin dashboard?

Render one AppShell in the group's layout with a Sidebar and a Topbar, and read the sidebar's cookie on the server so the first paint is right. The shell shows the sidebar beside the page on desktop, and a drawer plus a bottom tab bar on phones. It switches with CSS, so the server HTML is already right.

First, the router wiring: the Wingo UI navigation links render through LinkProvider, so one client provider turns them all into next/link:

// app/providers.tsx
"use client";

import type { ReactNode } from "react";
import Link from "next/link";
import { usePathname, useRouter } from "next/navigation";
import { Toaster } from "@/components/ui/toast";
import { LinkProvider } from "@/lib/navigation";

export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter();
  return (
    <LinkProvider component={Link} currentPath={usePathname()} navigate={router.push}>
      {children}
      {/* phones have a tab bar at the bottom, so toasts drop from the top */}
      <Toaster mobilePosition="top" />
    </LinkProvider>
  );
}

The sidebar and the tab bar share the NavItem shape, so one file feeds both:

// app/(admin)/nav.tsx
import { House, Settings, ShieldCheck, Users } from "lucide-react";
import type { SidebarNavGroup } from "@/components/ui/sidebar";
import type { NavItem } from "@/lib/navigation";

export const nav: SidebarNavGroup[] = [
  { items: [{ label: "Home", href: "/", icon: <House /> }] },
  { label: "Sales", items: [{ label: "Clients", href: "/clients", icon: <Users />, badge: 3 }] },
  {
    label: "Workspace",
    items: [
      { label: "Team", href: "/team", icon: <ShieldCheck /> },
      { label: "Settings", href: "/settings", icon: <Settings /> },
    ],
  },
];

export const tabs: NavItem[] = [
  { label: "Home", href: "/", icon: <House />, match: "exact" },
  { label: "Clients", href: "/clients", icon: <Users /> },
  { label: "Team", href: "/team", icon: <ShieldCheck /> },
  { label: "Settings", href: "/settings", icon: <Settings /> },
];

And the layout, a server component:

// app/(admin)/layout.tsx
import type { ReactNode } from "react";
import { cookies } from "next/headers";
import { AppShell } from "@/components/ui/app-shell";
import { Sidebar } from "@/components/ui/sidebar";
import { Topbar } from "@/components/ui/topbar";
import { getUser } from "@/server/dal";
import { nav, tabs } from "./nav";

export default async function AdminLayout({ children }: { children: ReactNode }) {
  const [store, user] = await Promise.all([cookies(), getUser()]);
  // the shell writes `${persistKey}-collapsed` ("app-shell" by default) as "true" or "false"
  const collapsed = store.get("app-shell-collapsed")?.value === "true";
  return (
    <AppShell
      defaultCollapsed={collapsed}
      mobileBreakpoint="lg"
      sidebar={<Sidebar groups={nav} filter user={{ name: user.name, email: user.email, avatar: user.avatarUrl }} />}
      topbar={<Topbar title="Northwind" />}
      tabs={tabs}
    >
      {children}
    </AppShell>
  );
}

Mod+B (Cmd on a Mac, Ctrl elsewhere) folds the sidebar into a 64px icon rail and stores that in the app-shell-collapsed cookie. Without the server read, a user who collapsed it sees it expanded on every first paint and then snap to the rail after hydration. Use the literal cookie name on the server: the persistedCookieName helper lives in a hook file that imports client-only React hooks, which a server layout cannot import. Below the breakpoint the sidebar becomes a drawer that closes on navigation, Escape, a tap outside or a swipe back, and focus returns to the menu button. A "Skip to content" link is the first Tab stop.

We pass mobileBreakpoint="lg" (1024px) on purpose. At md (768px), an 820px tablet in portrait keeps a 256px sidebar and 564px for the page, too little for a table. At lg it gets the phone layout and the full width.

Keep the awaits in this layout cheap: a slow await here holds every page behind it. A cookie read and a cached session lookup are fine; a dashboard query is not.

For comparison, the shadcn/ui Sidebar (as of October 2026) stores its open state in a sidebar_state cookie for seven days and renders a Sheet when its useIsMobile hook reports a phone. It has no bottom tab bar, so on a phone every destination is two taps away.

For the whole back office layout in one block, the Admin Shell adds a workspace switcher, a global search on /, notifications, a command menu on Mod+K and a five-tab bar whose More tab opens the drawer. Our React command palette guide covers that menu's shortcuts, nested pages and phone sheet.

How do you build the dashboard home with KPIs?

Fetch the numbers in the page for the period in the URL, and pass them to a dashboard block as props. The Admin Dashboard Page is the home of an orders business (four KPIs, revenue against the previous period, recent orders, what needs attention, team activity); the KPI Dashboard suits a B2B or analytics app.

The page reads the period, defaults to the last 30 days and fetches:

// app/(admin)/page.tsx
import { isValid, parseISO, startOfDay, subDays } from "date-fns";
import { getDashboard } from "@/server/dashboard";
import { getUser } from "@/server/dal";
import { DashboardHome } from "./dashboard-home";

function readPeriod(from?: string, to?: string) {
  const today = startOfDay(new Date());
  const end = to ? parseISO(to) : today;
  const start = from ? parseISO(from) : subDays(end, 29);
  return isValid(start) && isValid(end) ? { from: start, to: end } : { from: subDays(today, 29), to: today };
}

export default async function HomePage({ searchParams }: { searchParams: Promise<{ from?: string; to?: string }> }) {
  const { from, to } = await searchParams;
  const period = readPeriod(from, to);
  // { kpis, revenue, orders, tasks, activity, topProducts } for the period
  const [user, data] = await Promise.all([getUser(), getDashboard(period)]);
  return <DashboardHome firstName={user.firstName} period={period} data={data} />;
}

The view writes a new period back to the URL and sends order actions to Server Actions:

// app/(admin)/dashboard-home.tsx
"use client";

import { useRouter } from "next/navigation";
import { format } from "date-fns";
import { AdminDashboardPage } from "@/components/blocks/admin-dashboard-page";
import type { DashboardData } from "@/components/blocks/admin-dashboard-page-data";
import type { DateRange } from "@/components/ui/date-range-picker";
import { runOrderAction } from "./actions";

type Props = { firstName: string; period: DateRange; data: DashboardData };

export function DashboardHome({ firstName, period, data }: Props) {
  const router = useRouter();
  return (
    <AdminDashboardPage
      {...data}
      userName={firstName}
      defaultPeriod={period}
      onPeriodChange={({ from, to }) => {
        if (!from || !to) return;
        const params = new URLSearchParams({ from: format(from, "yyyy-MM-dd"), to: format(to, "yyyy-MM-dd") });
        router.replace(`/?${params}`, { scroll: false });
      }}
      onOrderAction={async (action, order) => {
        const { error } = await runOrderAction(action, order.id);
        if (error) throw new Error(error);
      }}
    />
  );
}

The period is uncontrolled on purpose (defaultPeriod): the date field updates the moment someone applies a range, and the panels follow when the server answers. onOrderAction is optimistic: the status changes at once, the row shows a spinner while the promise runs, and a rejection rolls it back with an error toast, which is why the handler throws on an error. One catch: after a cancel, the toast's Undo restores the row on screen only and calls none of your code, so the next server render shows the order as cancelled again. Rewrite labels.cancelDescription so users know a cancel is final; its default text promises an email and a refund, which only your server can keep.

Live demo: Admin Dashboard Page. The original article embeds an interactive demo here (Pick another period in the date field, then click an order in Recent orders to open its sheet. This frame is narrower than 1024px, so you see the phone layout: the sidebar sits behind the menu button and the tab bar holds the bottom edge). Try it live on wingo-ui.com or open the Admin Dashboard Page docs. Install: npx wingo-ui@latest add admin-dashboard-page

On a phone the KPIs sit two by two, recent orders become cards with Load more, and the date field and the order details open as bottom sheets you drag down to close.

When should you use the KPI Dashboard instead?

When the home is about analytics more than orders: revenue over time, sales by source, a conversion funnel, top salespeople and invoices. It takes one data object and hides a widget whose data is missing, so it fits a company with no funnel. It has the controls an analytics page needs: onRefresh (a promise spins the button and announces the update), onExport with CSV and PDF, a widgets list to pick and order panels, and widgetErrors with onWidgetRetry to show an error and a Try again button inside the one widget whose query failed, so the rest of the page stays up.

Its grid uses container queries: one column, two from 672px and three from 1152px of its own width. Inside a shell that matters, because a 1280px window with a 256px sidebar leaves about 1000px, and viewport breakpoints would lay the grid out for space it does not have. The DashboardWidget and KpiDashboardGrid parts are exported for your own panels.

Can you render KPI cards from a server component?

Yes, as long as every prop is data. The Stat Card takes numbers, strings and icons, so a server component can render a row directly:

// app/(admin)/reports/page.tsx
import { FileText, Timer, UserPlus, Wallet } from "lucide-react";
import { StatCard, StatGroup } from "@/components/ui/stat-card";
import { getKpis } from "@/server/reports";

export default async function ReportsPage() {
  const k = await getKpis();
  return (
    <StatGroup variant="joined">
      <StatCard label="Revenue" icon={<Wallet />} value={k.revenue} format="currency" delta={k.revenueChange} deltaLabel="vs. last month" sparkline={k.dailyRevenue} goal={k.revenueGoal} locale="en-US" />
      <StatCard label="Invoices issued" icon={<FileText />} value={k.invoices} delta={k.invoicesChange} deltaFormat="number" locale="en-US" />
      <StatCard label="New clients" icon={<UserPlus />} value={k.newClients} delta={k.newClientsChange} locale="en-US" />
      <StatCard label="Time to payment" icon={<Timer />} value={k.secondsToPay} format="duration" delta={k.timeToPayChange} invertTrend locale="en-US" />
    </StatGroup>
  );
}

The server HTML holds the final numbers, the count-up runs on the client when a card scrolls into view, and screen readers hear one sentence with the final value and the change. invertTrend makes a drop in time to payment green. Two limits: a function prop such as formatDelta needs a client file, and href renders a plain anchor (a full page load in Next.js), so linked tiles need a client wrapper whose onClick calls event.preventDefault() and then router.push.

How do you build list pages with a server-side data table?

Run the Data Table in server mode, keep its query in the URL, and let the page fetch one page at a time. In mode="server" the table does no sorting, filtering or paging itself: data is the current page, rowCount the total, and every change arrives in onQueryChange as one object (page, pageSize, sorting, globalFilter, columnFilters). One module translates it to and from the search params:

// app/(admin)/clients/query.ts
import type { DataTableQuery } from "@/components/ui/data-table";

type Params = Record<string, string | string[] | undefined>;
const one = (value: string | string[] | undefined) => (Array.isArray(value) ? value[0] : value) ?? "";

export function readQuery(params: Params): DataTableQuery {
  const [sortId, dir] = one(params.sort).split(".");
  const status = one(params.status);
  const size = Number(one(params.size));
  return {
    page: Math.max(1, Number(one(params.page)) || 1),
    pageSize: [10, 25, 50, 100].includes(size) ? size : 25,
    sorting: sortId ? [{ id: sortId, desc: dir === "desc" }] : [],
    globalFilter: one(params.q),
    columnFilters: status ? [{ id: "status", value: status.split(",") }] : [],
  };
}

export function writeQuery(query: DataTableQuery): string {
  const params = new URLSearchParams();
  if (query.page > 1) params.set("page", String(query.page));
  if (query.pageSize !== 25) params.set("size", String(query.pageSize));
  if (query.globalFilter) params.set("q", query.globalFilter);
  const sort = query.sorting[0];
  if (sort) params.set("sort", `${sort.id}.${sort.desc ? "desc" : "asc"}`);
  const status = query.columnFilters.find((filter) => filter.id === "status")?.value;
  if (Array.isArray(status) && status.length) params.set("status", status.join(","));
  return params.toString();
}

The page parses the URL and queries one page:

// app/(admin)/clients/page.tsx
import { listClients } from "@/server/clients";
import { ClientsTable } from "./clients-table";
import { readQuery } from "./query";

type Search = Promise<Record<string, string | string[] | undefined>>;

export default async function ClientsPage({ searchParams }: { searchParams: Search }) {
  const query = readQuery(await searchParams);
  // checks the session, whitelists sort ids and filter values before building SQL
  const { rows, total } = await listClients(query);
  return <ClientsTable rows={rows} total={total} initial={query} />;
}

The view starts from the URL and writes changes back in a transition, so isPending drives the refreshing bar:

// app/(admin)/clients/clients-table.tsx
"use client";

import { useTransition } from "react";
import { useRouter } from "next/navigation";
import { DataTable, createColumns, type DataTableQuery } from "@/components/ui/data-table";
import { writeQuery } from "./query";

export type ClientRow = { id: string; name: string; city: string; status: string; balance: number; lastInvoice: string | null };

const STATUSES = ["Active", "Overdue", "Prospect"];

const col = createColumns<ClientRow>();
const columns = col([
  col.accessor("name", { header: "Client", mobile: "title" }),
  col.accessor("city", { header: "City", mobile: "subtitle" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Active: { tone: "success" }, Overdue: { tone: "danger" }, Prospect: { tone: "info" } },
    filter: "multi-select",
    // server mode only sees one page, so list every option yourself
    filterOptions: STATUSES.map((status) => ({ value: status, label: status })),
    mobile: "meta",
  }),
  col.accessor("balance", { header: "Balance", type: "currency" }),
  col.accessor("lastInvoice", { header: "Last invoice", type: "relative" }),
]);

type Props = { rows: ClientRow[]; total: number; initial: DataTableQuery; loading?: boolean };

export function ClientsTable({ rows, total, initial, loading }: Props) {
  const router = useRouter();
  const [pending, startTransition] = useTransition();
  return (
    <DataTable
      data={rows}
      columns={columns}
      mode="server"
      rowCount={total}
      defaultPage={initial.page}
      defaultPageSize={initial.pageSize}
      defaultSorting={initial.sorting}
      defaultGlobalFilter={initial.globalFilter}
      defaultColumnFilters={initial.columnFilters}
      onQueryChange={(query) => {
        const search = writeQuery(query);
        startTransition(() => router.replace(search ? `/clients?${search}` : "/clients", { scroll: false }));
      }}
      refreshing={pending}
      loading={loading}
      quickFilters={[{ id: "overdue", label: "Overdue", columnFilter: { id: "status", value: ["Overdue"] } }]}
      onRowClick={(row) => router.push(`/clients/${row.id}`)}
      caption="Clients"
      locale="en-US"
    />
  );
}

Details that save debugging time: onQueryChange does not fire on the first render (the server already sent that page), the search arrives debounced (300ms), and the page resets to 1 when the search, a filter or the sort changes. The table is uncontrolled (default* props), so the search box never lags behind a server round trip. The trade-off: the back button changes the data while the toolbar keeps the last query. If your users live on the back button, control page, sorting, globalFilter and columnFilters from the URL instead.

Live demo: Data Table. The original article embeds an interactive demo here (Search, sort or click the Overdue chip: in server mode the table hands your code one query object, printed under the pager. Below 768px every row is a card you can long press to select). Try it live on wingo-ui.com or open the Data Table docs. Install: npx wingo-ui@latest add data-table

On a phone the columns become cards: mobile: "title" is the heading, subtitle the line under it, meta the badge in the corner. Sorting, filters and the row menu open as bottom sheets, and with selectionMode on, a long press starts selection. Server mode keeps a compact pager on phones; client mode uses Load more.

Server mode is not always the right call. When one request can load every row a user may see, client mode filters instantly and needs no query API. We switch to server mode past a few thousand rows, or when permissions decide which rows exist for a user. To build the table yourself on TanStack Table instead, with the same server pagination, follow our TanStack Table v9 data table tutorial.

How do you build a settings page that never loses input?

Let one block own the drafts, and save through Server Actions that return their errors. The Settings Page has six sections (profile, account, notifications, billing, security, danger zone). A text change slides up a save bar with Discard and Save (or Mod+S), switches save on their own, a failed save keeps the draft and shows the message, and leaving a section with unsaved changes asks first.

Next.js recommends modeling expected errors as return values in Server Functions, and in production the client does not get the original message of a server error, so a thrown "This workspace address is taken" would arrive as a generic error:

// app/(admin)/settings/actions.ts
"use server";

import { verifySession } from "@/server/dal";
import { saveSettings } from "@/server/settings";

export type ActionResult = { error?: string };

export async function saveSection(section: string, values: unknown): Promise<ActionResult> {
  const { userId } = await verifySession();
  // validates with zod and returns { error } for anything the user can fix
  return saveSettings(userId, section, values);
}

// savePreference(preference, value) has the same shape. verifyEmailCode(email, code),
// verifyTwoFactorCode(code) and checkWorkspaceAddress(slug) check the session too
// and resolve to a boolean (true: the code is right, the address is free)

The view turns a returned error into the rejection the block listens for, and replaces the block's demo checks with real ones:

// app/(admin)/settings/settings-view.tsx
"use client";

import { SettingsPage, type SettingsPageProps } from "@/components/blocks/settings-page";
import {
  checkWorkspaceAddress,
  savePreference,
  saveSection,
  verifyEmailCode,
  verifyTwoFactorCode,
  type ActionResult,
} from "./actions";

type Props = Pick<
  SettingsPageProps,
  | "profile"
  | "account"
  | "notifications"
  | "billing"
  | "plans"
  | "sessions"
  | "passwordChangedAt"
  | "defaultTwoFactorEnabled"
  | "twoFactorSecret"
  | "twoFactorUri"
  | "backupCodes"
>;

const LABELS = { codeHint: "Enter the 6-digit code." };

async function check(result: Promise<ActionResult>) {
  const { error } = await result;
  if (error) throw new Error(error);
}

export function SettingsView(props: Props) {
  return (
    <SettingsPage
      {...props}
      onSave={(section, values) => check(saveSection(section, values))}
      onPreferenceChange={(preference, value) => check(savePreference(preference, value))}
      verifyEmailCode={verifyEmailCode}
      verifyTwoFactorCode={verifyTwoFactorCode}
      checkWorkspaceAddress={checkWorkspaceAddress}
      labels={LABELS}
    />
  );
}

Pass every data prop from the page: anything you leave out falls back to the block's sample data. The security defaults are demo values on purpose. Without verifyEmailCode and verifyTwoFactorCode, the code 123456 passes; without twoFactorSecret, twoFactorUri and backupCodes, the setup dialog shows sample ones; and the default codeHint label reads "In this demo, the code is 123456." Generate the secret and backup codes on the server for the signed-in user.

The dialogs take handlers with the same promise contract (onEmailChange, onPasswordChange, onTwoFactorChange, onSessionRevoke, onPlanChange, onDeleteAccount). One naming detail: the section ids are internal (profil, cont, notificari, facturare, securitate, pericol), so map them to your own segments if each section gets a URL through onSectionChange.

Live demo: Settings Page. The original article embeds an interactive demo here (Open Profile, edit the full name and press Save. This demo drops the first save on purpose: the bar shows the error and your edit stays, and the next Save goes through. In a frame this narrow the sections are a list that pushes each one in). Try it live on wingo-ui.com or open the Settings Page docs. Install: npx wingo-ui@latest add settings-page

From 768px the sections are a column on the left (or tabs with nav="tabs"). On a phone each section pushes in with a back button and a swipe back, dialogs open as bottom sheets, and the save bar is pinned above the tab bar. The block validates each form before it calls onSave: invalid fields turn red and the first one takes focus, the pattern our React form components guide covers field by field.

How do you build the team and roles page?

Treat every control on it as a request the server can refuse. The Users Admin Page has three tabs: Members (the team and pending invitations against your seats, a role picker per row), Roles and permissions (a matrix with a save bar) and Audit log (a filterable history with CSV export). The server decides who may manage and enforces the rules the interface shows:

// app/(admin)/team/actions.ts
"use server";

import { requireAdmin } from "@/server/dal";
import { changeMemberRole } from "@/server/team";

export async function changeRole(memberId: string, role: string): Promise<{ error?: string }> {
  const admin = await requireAdmin();
  // refuses to demote the last administrator, the same rule the picker shows
  return changeMemberRole(admin.workspaceId, memberId, role);
}
// invite, removeMember and savePermissions follow the same shape

// app/(admin)/team/team-view.tsx
"use client";

import { UsersAdminPage, type UsersAdminPageProps } from "@/components/blocks/users-admin-page";
import { changeRole, invite, removeMember, savePermissions } from "./actions";

type Props = Pick<
  UsersAdminPageProps,
  "companyName" | "members" | "invites" | "roles" | "permissionRoles" | "permissionGroups" | "defaultPermissions" | "auditEvents" | "seats" | "canManage"
>;

async function check(result: Promise<{ error?: string }>) {
  const { error } = await result;
  if (error) throw new Error(error);
}

export function TeamView(props: Props) {
  return (
    <UsersAdminPage
      {...props}
      onInvite={(input) => check(invite(input))}
      onRoleChange={(member, role) => check(changeRole(member.id, role))}
      onRemove={(member) => check(removeMember(member.id))}
      onPermissionsSave={(value) => check(savePermissions(value))}
    />
  );
}

The page computes canManage from the session and passes it with the data. With canManage={false} the block turns read-only and says why, which beats hiding the page from people who only need to see who has access.

The interface guards the obvious mistakes: the last administrator cannot be demoted, nobody removes themselves or the owner, and invitations hold a seat. Those guards are for the person clicking; your actions enforce them again, because a Server Action cannot tell which button sent the request. Likewise the block adds this page's changes to the top of the audit log as feedback, but the real audit rows are the ones your server writes in the same transaction.

On a phone, members become cards with the role picker inside, the invite dialog is a bottom sheet, and the matrix shows one role at a time with chips, because five role columns do not fit 390px. The parts also ship alone: Members Table, Permissions Matrix and Audit Log.

How do you handle loading and error states in the admin?

Give every route a loading.tsx that renders the same component with its loading prop, and the group one error.tsx. loading.js shows its fallback immediately on navigation while the shell stays interactive, and a skeleton in the real layout means nothing jumps when the data arrives:

// app/(admin)/clients/loading.tsx
import { ClientsTable } from "./clients-table";
import { readQuery } from "./query";

export default function Loading() {
  return <ClientsTable rows={[]} total={0} initial={readQuery({})} loading />;
}

The Data Table draws skeleton rows in its column layout (cards on phones), and the dashboard, settings and team blocks have the same prop. A route without its own loading.tsx falls back to the nearest parent's, so one group-level skeleton would flash the same layout before every page.

For errors, Next.js 16.3 made the retry prop of error.js stable; it re-fetches and re-renders the segment:

// app/(admin)/error.tsx
"use client";

import { Button } from "@/components/ui/button";

export default function AdminError({ error, retry }: { error: Error & { digest?: string }; retry: () => void }) {
  return (
    <div role="alert" className="mx-auto flex max-w-md flex-col items-center gap-3 px-4 py-16 text-center">
      <h2 className="text-lg font-semibold">This page did not load</h2>
      <p className="text-sm text-muted-foreground">If it keeps failing, send us this reference: {error.digest ?? "none"}</p>
      <Button onClick={retry}>Try again</Button>
    </div>
  );
}

Empty states belong in the components: the Data Table's emptyState for a list with no rows yet and noResultsState when filters match nothing, so "No clients yet" and "Nothing matches" never get mixed up.

How do you make every admin screen usable on a phone?

Change behavior as well as layout, and check each screen at 390px on a real phone. People open a back office on phones to approve an expense, check an order or answer a client. The checklist we hold every admin screen to:

Navigation: everything in a drawer behind the menu button, plus a tab bar for the three to five daily destinations; tablets in portrait get the phone layout.
One bar on the bottom edge: the tab bar pads the home indicator and publishes its height as --bottom-bar-offset, and the settings and team save bars read it to sit above the tab bar.
Numbers: KPIs two per row, with values that shrink to fit 360px instead of wrapping.
Tables: rows become cards (title, subtitle, badge, up to four fields); nobody should scroll sideways to read one record.
Overlays: menus, filters, date pickers and detail views open as bottom sheets you can drag down; confirmations stay centered.
Container queries: inside a shell, measure the container (as the KPI grid does), so a sidebar never squeezes a layout built for the viewport.
Touch: 44px targets on coarse pointers, no hover-only actions, and every gesture backed by a visible button.

Our mobile-first React components guide covers the bottom sheets, touch targets, safe areas and phone tables in depth, with code, and the React bottom navigation bar guide covers the tab bar and when the sidebar alone is enough.

Should you start from a Next.js admin template or build it yourself?

Start from a free starter to learn the App Router or when you already use its stack; build from blocks when settings, roles and phone layouts must work on day one. Before you pick a "nextjs admin template" or a "shadcn admin dashboard", compare these free starting points with the blocks in this guide (as of October 2026):

Option	Price and license	What you get	What is left to you
Next.js Learn dashboard course	Free	A financial dashboard with Postgres, Server Actions, search and pagination in the URL, NextAuth.js and Proxy; its invoices table turns into cards on phones	Settings, team and roles; it teaches the patterns and leaves the screens to you
shadcn/ui dashboard-01 block	Free, MIT	Inset sidebar, summary cards, an interactive area chart and a TanStack data table (`npx shadcn add dashboard-01`)	Settings, team pages, auth; the table keeps its rows on a phone and scrolls sideways
next-shadcn-dashboard-starter	Free, MIT	Next.js 16, shadcn/ui on Base UI, Clerk auth, product and user tables with URL state, team, billing and profile pages	Team, roles and billing come from Clerk's prebuilt components, so they need Clerk
Wingo UI blocks (this guide)	Pro: $8 a month, $80 a year or $150 lifetime	App Shell, Admin Shell, the two dashboards, Data Table, Settings Page and Users Admin Page, all with phone layouts	Your data layer and auth; the blocks are UI only

Where the free options win: to learn, take the Next.js course, which teaches the data and auth side this guide skips. If you run shadcn/ui and need a dashboard tonight, dashboard-01 is one command and you own the code, which makes it the shortest path if you searched for "nextjs admin dashboard shadcn"; for desk-only internal tools a sideways-scrolling table is acceptable. If you already use Clerk, the Kiranism starter wires organizations, team management and billing through Clerk's prebuilt components. Wingo UI earns its price when phone users matter and you do not want to build the settings, team and table behaviors yourself. For libraries in general, our shadcn alternatives comparison covers fourteen with dated prices.

What should you build first?

Build the shell first, then one list page, then the home. The shell sets the navigation and phone layout every screen inherits, a list page exercises the server path (URL, query, Server Actions) that settings and team reuse, and the home is easiest once real data exists.

The admin blocks in this guide are part of Wingo UI Pro. With it, start with npx wingo-ui@latest add app-shell (it brings the Sidebar, Topbar, Bottom Tab Bar and the hooks along) and drop it into app/(admin)/layout.tsx as above. The free basics they build on, such as the Button, Card, Badge, Dialog and Toast, install without an account. For back offices that bill Romanian customers, two tutorials go deeper: e-Factura VAT calculation computes VAT per rate the way ANAF validates it, with an editable invoice, and the Romanian address format guide builds a delivery address form with county, locality and postal code checks. More screen-by-screen tutorials live in Build it: screens and apps.

Components in this post

App Shell (Pro): The whole admin layout in one component: a collapsible, resizable sidebar, a top bar and the page; a drawer and a tab bar on phones. Install: npx wingo-ui@latest add app-shell
Admin Dashboard Page (Pro): The home of a back office: greeting and period, four KPIs, revenue against the previous period, recent orders, alerts and team activity. Install: npx wingo-ui@latest add admin-dashboard-page
KPI Dashboard (Pro): The first screen of a back office: KPI tiles with deltas, revenue against the last period, sources, funnel, top sellers, invoices, activity. Install: npx wingo-ui@latest add kpi-dashboard
Data Table (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: npx wingo-ui@latest add data-table
Sidebar (Pro): The admin sidebar: grouped links with icons, nested sections, badges, a sliding active pill, an icon rail with flyouts and a filter. Install: npx wingo-ui@latest add sidebar
Stat Card (Pro): The KPI tile of a dashboard: a label, a big number that counts up, a delta pill that knows good from bad, a sparkline and a goal bar. Install: npx wingo-ui@latest add stat-card
Settings Page (Pro): The account settings of a back office: profile, account, notifications, billing, security and a danger zone, with a save bar. Install: npx wingo-ui@latest add settings-page
Users Admin Page (Pro): The team page of a back office: members and invitations with seats, roles with a permissions matrix and a save bar, and the audit log. Install: npx wingo-ui@latest add users-admin-page

FAQ

How should I structure a Next.js App Router project for an admin dashboard?

Put every admin route in a route group such as app/(admin) whose layout renders the shell, and keep sign-in in a separate group without it. Pages are server components that fetch through a server-only data access layer, and each route gets its own loading.tsx.

Is there a free shadcn admin dashboard for Next.js?

Yes. As of October 2026 shadcn/ui ships a free dashboard-01 block (npx shadcn add dashboard-01) with a sidebar, summary cards, a chart and a data table, but settings, roles and a phone layout for the table are left to you. The MIT next-shadcn-dashboard-starter adds Clerk auth, product and user tables, and team, billing and profile pages built on Clerk's prebuilt components.

Should an admin data table filter on the server or in the browser?

Filter in the browser when one request can load every row the user may see; it is instant and needs no query API. Filter on the server when the data grows past a few thousand rows or permissions decide which rows a user sees, and keep the page, sort, search and filters in the URL.

Where do auth checks go in a Next.js admin dashboard?

In a server-only data access layer that every page and every Server Action calls. A check in the layout or in proxy.ts alone is too weak: layouts do not re-render on client navigation, and Server Actions can be called with a direct POST request.

How do I make an admin dashboard usable on a phone?

Move the sidebar into a drawer with a bottom tab bar, show KPIs two per row, turn table rows into cards, open menus and detail views as bottom sheets, and keep a single bar on the bottom edge above the safe area. Test at 390px on a real phone, because a narrowed desktop window has no touch and no on-screen keyboard.

Which Wingo UI admin components are free?

None of the admin blocks in this guide: the App Shell, Sidebar, Data Table, Stat Card, KPI Dashboard, Admin Dashboard Page, Settings Page and Users Admin Page are Pro. The free basics, such as Button, Card, Badge, Dialog, Select, Tabs and Toast, install with the CLI without an account.

This article was originally published on the Wingo UI blog: Nextjs Admin Dashboard Tutorial: 5 Screens, Phone-Ready. The original has the live, interactive demos and is kept up to date.

React 19 forwardRef Migration: ref as a Prop in TypeScript

Serban Dan Rusu — Mon, 02 Nov 2026 15:00:00 +0000

TL;DR

In React 19, function components receive ref as a regular prop, so you delete forwardRef, read ref from props (or let it travel in ...props) and type it with ComponentProps or Ref<HTMLInputElement>. forwardRef still works in React 19.3 and logs no warning, but React plans to deprecate it, and a library that supports React 18 has to keep it. The parts that need care are merged refs, which should pass on cleanup functions, and asChild, where the ref belongs on the child element.

Your components are full of forwardRef wrappers, displayName lines and ComponentPropsWithoutRef types, and React 19 says you no longer need them. The React 19 forwardRef change is small on paper: function components now receive ref as a regular prop. The work is at the edges. Props types that strip the ref, components that need the DOM node themselves, and asChild wrappers that hand the ref to a child all behave a little differently once the wrapper is gone. This tutorial migrates an input and a button, checked against React 19.3 and TypeScript 5.9, and shows the patterns we use in Wingo UI, whose source does not call forwardRef once.

What changed about forwardRef in React 19?

Function components get ref in their props, so the wrapper has nothing left to do. The React 19 release post says new function components "will no longer need forwardRef" and that React will "deprecate and remove forwardRef" in future versions. The forwardRef reference says the same: no longer necessary, deprecated in a future release.

So the React 19 forwardRef replacement is the ref prop itself. Four facts decide how you migrate:

forwardRef still works and stays quiet. We searched the development builds of react and react-dom 19.3.0 for a deprecation message and found none. Old components keep running while you migrate.
Class components did not change. A ref passed to a class still points to the instance and never shows up in its props.
element.ref is on its way out. React 19 still fills it, but reading it in development logs "Accessing element.ref was removed in React 19. ref is now a regular prop." Read element.props.ref instead.
React 18 strips ref from props. A library that still lists React 18 as a peer dependency has to keep forwardRef. Radix does: @radix-ui/react-slot 1.3.3 wraps its Slot in React.forwardRef and accepts React 16.8 through 19. Wingo UI requires React 19, so its components take ref as a plain prop.

How do you migrate a component from forwardRef to ref as a prop?

Delete the wrapper, type the props with ComponentProps, and let the ref travel in ...props. Here is the classic shadcn-style input before:

// components/ui/input.tsx (React 18)
import * as React from "react";
import { cn } from "@/lib/utils";

const Input = React.forwardRef<HTMLInputElement, React.ComponentPropsWithoutRef<"input">>(
  ({ className, type = "text", ...props }, ref) => (
    <input ref={ref} type={type} className={cn("h-10 w-full rounded-[10px] px-3", className)} {...props} />
  ),
);
Input.displayName = "Input";

export { Input };

And after:

// components/ui/input.tsx (React 19)
import type { ComponentProps } from "react";
import { cn } from "@/lib/utils";

export function Input({ className, type = "text", ...props }: ComponentProps<"input">) {
  return (
    <input
      data-slot="input"
      type={type}
      className={cn("h-10 w-full rounded-[10px] px-3", className)}
      {...props}
    />
  );
}

ComponentProps<"input"> already contains ref?: Ref<HTMLInputElement>, so the spread hands it to the <input> and <Input ref={inputRef} /> works without one ref-specific line. A named function gives React DevTools its name, so displayName goes too.

For a whole folder, start with the official codemod from reactjs/react-codemod, on a clean branch so you can read the diff:

npx codemod react/19/remove-forward-ref --target components/ui

shadcn/ui made the same move when it switched to React 19. The shadcn Tailwind v4 guide lists the manual steps: replace React.forwardRef<...> with React.ComponentProps<...>, remove ref={ref}, add a data-slot attribute, convert to a named function and drop displayName. Their current Button types its props as React.ComponentProps<"button"> plus its variants and asChild. If your project still has the older shadcn forwardRef components with local edits, updating shadcn components without losing edits covers the merge.

To keep forwardRef from coming back, add a lint rule. As of October 2026, eslint-react's no-forward-ref is in its recommended presets, and Biome's noReactForwardRef (since Biome 2.2.5) is opt-in with an unsafe fix. Leave them off in packages that still support React 18.

How do you type ref as a prop in React 19 with TypeScript?

Most of the time you type nothing, because ComponentProps<"button"> includes ref. You add ref?: Ref<HTMLButtonElement> only when you write the props type yourself. The other type changes are deletions and renames:

React 18 pattern	React 19 replacement
`forwardRef<HTMLInputElement, Props>(...)`	`ref?: Ref<HTMLInputElement>` in `Props`, or `ComponentProps<"input">`
`ComponentPropsWithoutRef<"input">` for a wrapper	`ComponentProps<"input">` (the old type strips the ref you now pass on)
`ComponentPropsWithoutRef<typeof Root>` plus `ElementRef<typeof Root>`	`ComponentProps<typeof Root>`, and `ComponentRef<typeof Root>` when you need the node type (`ElementRef` is deprecated)
`child.ref` on a React element	`child.props.ref`
`useRef<HTMLInputElement>()`	`useRef<HTMLInputElement>(null)` (an argument is now required)
`ref={(node) => (el = node)}`	`ref={(node) => { el = node; }}` (a returned value now reads as a cleanup)

The last row trips people up the day they upgrade @types/react. Ref callbacks may return a cleanup function now, so an arrow function that implicitly returns the node fails with Type 'HTMLDivElement | null' is not assignable to type 'void | (() => VoidOrUndefinedOnly)'. Add braces and it compiles.

When the props are your own, declare the ref like any other prop:

import type { ReactNode, Ref } from "react";

type IconButtonProps = {
  label: string;
  icon: ReactNode;
  onPress?: () => void;
  ref?: Ref<HTMLButtonElement>;
};

export function IconButton({ label, icon, onPress, ref }: IconButtonProps) {
  return (
    <button ref={ref} type="button" aria-label={label} onClick={onPress}>
      {icon}
    </button>
  );
}

Generic components get their type parameter back

Generic components gain the most from ref as a prop in React 19. forwardRef returns a component that is not generic, so a typed list needed a cast to get its <T> back:

// React 18: forwardRef drops <T>, so the signature is cast back on
export const List = forwardRef(ListInner) as <T>(
  props: ListProps<T> & { ref?: Ref<HTMLUListElement> },
) => ReturnType<typeof ListInner>;

Now it is a plain generic function, and T is inferred at the call site with the ref still typed:

import type { ComponentProps, ReactNode } from "react";

type ListProps<T> = Omit<ComponentProps<"ul">, "children"> & {
  items: T[];
  getKey: (item: T) => string;
  renderItem: (item: T) => ReactNode;
};

export function List<T>({ items, getKey, renderItem, ...props }: ListProps<T>) {
  return (
    <ul {...props}>
      {items.map((item) => (
        <li key={getKey(item)}>{renderItem(item)}</li>
      ))}
    </ul>
  );
}

// <List ref={listRef} items={customers} getKey={(c) => c.id} renderItem={(c) => c.name} />

Wrapper layers pass the ref without extra code

In our Button the ref never appears by name. ButtonProps is Omit<ComponentProps<"button">, "color" | ...> plus our props. The component reads them through useDefaults("button", buttonProps), which layers app-wide defaults from UIProvider under the props passed in, and spreads the rest onto motion.button. With forwardRef the ref would arrive as a second argument, and every layer between the caller and the element would need its own way to carry it. As a prop, it is one more key.

How do you merge refs in React 19?

Merge the two refs in a memoized callback ref that returns a cleanup. You need this when the component uses the DOM node itself and the caller wants it too. Our Input is the real case. It needs the node to clear the text with a real input event, put focus back after clearing and hear form resets, and your code needs the same node to focus the field after a failed submit. This is the pattern from components/ui/input.tsx, trimmed to a search field:

"use client";

import { useCallback, useRef, type ComponentProps, type Ref } from "react";

// hands the node to the caller's ref and returns the matching cleanup
function attachRef<T>(ref: Ref<T> | undefined, node: T) {
  if (typeof ref === "function") {
    const cleanup = ref(node);
    return () => (typeof cleanup === "function" ? cleanup() : ref(null));
  }
  if (ref) {
    const object = ref;
    object.current = node;
    return () => {
      object.current = null;
    };
  }
  return undefined;
}

// writes through the prototype setter so React sees the change, then fires the event onChange listens to
function clearValue(input: HTMLInputElement) {
  Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set?.call(input, "");
  input.dispatchEvent(new Event("input", { bubbles: true }));
}

export function SearchField({ ref, ...props }: ComponentProps<"input">) {
  const inputRef = useRef<HTMLInputElement | null>(null);

  const setRef = useCallback(
    (node: HTMLInputElement | null) => {
      inputRef.current = node;
      const detach = attachRef(ref, node);
      return () => {
        inputRef.current = null;
        detach?.();
      };
    },
    [ref],
  );

  return (
    <div className="flex items-center gap-2">
      <input ref={setRef} type="search" {...props} />
      <button
        type="button"
        onClick={() => {
          if (!inputRef.current) return;
          clearValue(inputRef.current);
          inputRef.current.focus();
        }}
      >
        Clear
      </button>
    </div>
  );
}

Three details matter:

Cleanups. When the node goes away, React 19 calls the cleanup a ref callback returned, instead of calling the callback again with null. So attachRef runs the caller's cleanup if they returned one and falls back to ref(null) if they did not.
A stable callback. useCallback keeps setRef the same between renders. A new callback ref on every render makes React detach and reattach it each time. In a StrictMode test, an inline ref callback logged its cleanup and a fresh attach after a plain re-render, while the memoized one stayed attached.
A clear React can hear. clearValue goes through the native value setter and fires an input event, so the caller's onChange runs with an empty value, like after a keystroke. Assigning input.value = "" empties the field without telling React or a form library.

Textarea merges refs the same way, so it can measure its own node and grow with its content.

Using it from the outside is a normal ref:

"use client";

import { useRef } from "react";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";

export function SignupForm() {
  const emailRef = useRef<HTMLInputElement>(null);

  return (
    <form
      noValidate
      onSubmit={(event) => {
        event.preventDefault();
        const email = emailRef.current?.value.trim() ?? "";
        if (!email.includes("@")) emailRef.current?.focus();
      }}
      className="flex flex-col gap-3"
    >
      <Input ref={emailRef} type="email" label="Email" placeholder="emma.carter@example.com" clearable />
      <Button type="submit">Create account</Button>
    </form>
  );
}

React Hook Form's register passes a ref the same way, so {...register("email")} reaches the <input> with no adapter. The React form components guide covers which fields need Controller instead.

Live demo: Input. The original article embeds an interactive demo here (Press Continue with a short title: the demo's own ref moves focus back to the field. Then type and press Escape or tap the clear button: the Input's internal ref empties it and keeps focus). Try it live on wingo-ui.com or open the Input docs. Install: npx wingo-ui@latest add input

When you expose methods instead of a node, useImperativeHandle(ref, ...) works exactly as before, with ref from props. Our Pro Schema Builder hands out validate() and getJsonSchema() that way; see pricing for what Pro includes.

How does ref as a prop work with asChild and Slot?

Spread the props, ref included, onto Slot, and put the ref on the child when you need the child's type. Radix Slot composes the ref it receives with the child's own ref. In React 19 it reads the child's ref from element.props.ref, so neither one is lost and no warning fires.

The trap is TypeScript. A button component types its ref for <button>, so passing a link ref to the wrapper fails:

import Link from "next/link";
import { useRef } from "react";
import { Button } from "@/components/ui/button";

export function UpgradeLink() {
  const linkRef = useRef<HTMLAnchorElement>(null);

  // error: Type 'RefObject<HTMLAnchorElement | null>' is not assignable to type 'Ref<HTMLButtonElement> | undefined'
  return (
    <Button asChild ref={linkRef}>
      <Link href="/pricing">See plans</Link>
    </Button>
  );
}

Put the ref on the child. Slot merges it with its own, and the type is right:

"use client";

import Link from "next/link";
import { useEffect, useRef } from "react";
import { Button } from "@/components/ui/button";

export function UpgradeLink({ highlight }: { highlight: boolean }) {
  const linkRef = useRef<HTMLAnchorElement>(null);

  useEffect(() => {
    if (highlight) linkRef.current?.focus();
  }, [highlight]);

  return (
    <Button asChild variant="outline">
      <Link ref={linkRef} href="/pricing">
        See plans
      </Link>
    </Button>
  );
}

Our Button renders asChild through motion.create(Slot), so two refs want the same node: motion's, for the press spring, and yours. Slot composes both. We mounted this Button in Chromium under StrictMode with a plain anchor as the child: the child's ref received the <a>, and the console stayed empty.

Live demo: Button. The original article embeds an interactive demo here (This Button has asChild on, so it renders a link: press it for the same spring dip, and Tab to it for the same focus ring). Try it live on wingo-ui.com or open the Button docs. Install: npx wingo-ui@latest add button

Two more things break asChild after a migration:

A child component that drops the ref. Slot passes ref, className and event handlers to the child, and a component that does not spread its props loses all three. Radix tooltips and popovers find their trigger through that ref, so the content has no element to position against.
A homemade Slot that reads child.ref. It still works at runtime, but logs the element.ref error in development, and @types/react 19 no longer declares ref on ReactElement, so TypeScript rejects it too. Read it from props, with a type argument because element props default to unknown in React 19:

import { isValidElement, type ReactNode, type Ref } from "react";

type WithRef = { ref?: Ref<HTMLElement> };

// React 18 code read children.ref, which logs an error in React 19 development builds
export function getChildRef(children: ReactNode) {
  return isValidElement<WithRef>(children) ? children.props.ref : undefined;
}

What should you try next?

Install the two free components from this post and read how they handle refs in your own project:

npx wingo-ui@latest add button input

Both land in components/ui as source you own, along with the field, spinner and helpers they import, and none of those files use forwardRef. For the other half of the stack they target, browse the Next.js and Tailwind CSS guides, starting with Tailwind v4 design tokens.

Components in this post

Button (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: npx wingo-ui@latest add button
Input (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: npx wingo-ui@latest add input

FAQ

Is forwardRef deprecated in React 19?

Not formally. The React docs say forwardRef is no longer necessary in React 19 and will be deprecated in a future release. As of React 19.3 it still works and logs no warning, but new function components should take ref as a prop.

How do I type the ref prop in React 19 with TypeScript?

When you wrap one element, use ComponentProps<'button'>, which already includes ref. When you write the props type yourself, add ref?: Ref<HTMLButtonElement>. Stop using ComponentPropsWithoutRef for wrappers, and replace ElementRef with ComponentRef.

Do I still need forwardRef if my library supports React 18?

Yes. React 18 removes ref from props before your component runs, so only forwardRef gives you the ref there. Keep it until React 18 leaves your peer dependencies; forwardRef components still work in React 19.

Does asChild still work without forwardRef?

Yes. Radix Slot reads the child's ref from its props in React 19 and composes it with the ref the Slot receives. Put the ref on the child when you want its real type, such as HTMLAnchorElement for a link rendered through a button component.

Is there a codemod to remove forwardRef?

Yes. The reactjs/react-codemod project ships remove-forward-ref: run npx codemod react/19/remove-forward-ref --target components/ui on a clean branch, then review the diff, especially generic components and props types that still use ComponentPropsWithoutRef.

Do class components get ref as a prop in React 19?

No. A ref passed to a class component still points to the component instance and is not passed in its props.

This article was originally published on the Wingo UI blog: React 19 forwardRef Migration: ref as a Prop in TypeScript. The original has the live, interactive demos and is kept up to date.

dnd kit Mobile: Touch Drag That Lets the Page Scroll

Serban Dan Rusu — Mon, 02 Nov 2026 07:00:00 +0000

TL;DR

To make dnd kit mobile drag work without blocking the page scroll, replace the default sensors with a pointer sensor that ignores touch, a TouchSensor with a 250ms delay and 5 to 8px of tolerance, and a KeyboardSensor, then set touch-action: manipulation on long-press surfaces and touch-action: none only on drag handles. Keep the drag inside its own scroll container, because @dnd-kit/core cancels a drag on window resize and iOS Safari resizes the window when its toolbar collapses. Add a tap path, such as a Move to menu or up and down buttons, because keyboard drag alone does not meet WCAG 2.5.7.

You built a sortable list or a kanban board with dnd kit, it works with a mouse, and on a phone it falls apart: the page scrolls while the card stays put, or the card grabs every swipe and the list never scrolls. This tutorial fixes dnd kit mobile drag step by step: which sensors to register, the activation delay versus scroll trade-off, where touch-action goes, why iOS Safari cancels drags, and the keyboard and tap paths that make drag and drop accessible. The sensor setup is the one in the Wingo UI Kanban, which the Deal Pipeline builds on; the List shows the drag handle variant.

As of October 2026, the latest @dnd-kit/core is still 6.3.1 from December 2024, and the legacy docs recommend the new version of dnd kit (@dnd-kit/react for React), which is at 0.5.0, before 1.0. This post targets @dnd-kit/core 6.3.1 and @dnd-kit/sortable 10.0.0.

Why is dnd kit not working on mobile?

Because DndContext uses the PointerSensor and the KeyboardSensor by default, and pointer events cannot stop a scroll. When a finger moves on an element that allows panning, the browser starts scrolling and fires pointercancel, which ends the drag, and calling preventDefault() in pointermove changes nothing. The dnd kit Pointer sensor docs say it plainly: "Using touch-action: none; is the only way to reliably prevent scrolling for pointer events."

That leaves two tools, each with a cost:

touch-action: none on the draggable. The drag works, and a swipe that starts on that element can never scroll the page. Fine for a small grip, bad for a list of full-width rows: when every row is none, no swipe on the list scrolls it. The docs suggest none on a drag handle only, for this reason.
The TouchSensor. Touch events can be canceled in touchmove, so a drag can wait for a long press and still let a swipe scroll. The same docs page recommends the Mouse and Touch sensors whenever none does not fit your layout.

The problem is old: issue #435, "Dragging with PointerSensor does not work well on touch devices", dates from August 2021. When the rows themselves must scroll, React drag and drop on touch screen devices needs the TouchSensor, next to a sensor for the mouse.

Which dnd kit sensors work on a touch screen?

Three: a pointer sensor that ignores fingers, the dnd kit touch sensor with a delay, and the keyboard sensor. The trap is registering the stock PointerSensor next to the TouchSensor. A touch fires pointerdown before touchstart, and DndContext ignores a sensor's activator while another sensor is pending; the check in the 6.3.1 source is commented "Another sensor is already instantiating". So the PointerSensor takes every finger and the TouchSensor's delay never runs.

We tested it with @dnd-kit/core 6.3.1 in headless Chromium with emulated touch: one draggable on a page taller than the screen, an 8px distance on the pointer sensor, 250ms and 8px on the touch sensor, and a finger moving 60px either at once or after a 400ms hold.

Sensors	`touch-action`	Swipe at once	Hold 400ms, then move
PointerSensor + TouchSensor	`manipulation`	drag starts, then cancels as the page scrolls	the same: no long press ever lifts it
PointerSensor + TouchSensor	`none`	drag starts after 8px, the page cannot scroll	drag starts after 8px
pointer sensor that skips touch + TouchSensor	`manipulation`	the page scrolls, no drag	drag starts at 250ms, the page stays put

A common workaround picks one sensor by device type, which breaks on touch screen laptops, where one person uses both the trackpad and the screen. The last row is the cleaner fix: a PointerSensor subclass whose activator skips touch pointers, so the mouse and pen take the pointer path and fingers take the touch path. Our Kanban runs the same pointer and touch sensors. Save this as components/use-drag-sensors.ts; the full example at the end imports it:

"use client";

import { KeyboardSensor, PointerSensor, TouchSensor, useSensor, useSensors } from "@dnd-kit/core";
import { sortableKeyboardCoordinates } from "@dnd-kit/sortable";

// PointerSensor for mouse and pen only: fingers are left to the TouchSensor
export class MousePointerSensor extends PointerSensor {
  static activators = [
    {
      eventName: "onPointerDown" as const,
      handler: ({ nativeEvent: event }: { nativeEvent: PointerEvent }) =>
        event.isPrimary && event.button === 0 && event.pointerType !== "touch",
    },
  ];
}

export function useDragSensors() {
  return useSensors(
    // mouse and pen: 8px of travel, so a click is still a click
    useSensor(MousePointerSensor, { activationConstraint: { distance: 8 } }),
    // touch: a 250ms press, so a swipe still scrolls
    useSensor(TouchSensor, { activationConstraint: { delay: 250, tolerance: 8 } }),
    // keyboard: Space or Enter lifts, arrows move, Space or Enter drops, Escape cancels
    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
  );
}

The stock MouseSensor plus TouchSensor pairing from the docs works too.

What delay and tolerance should the TouchSensor use?

250ms with 5 to 8px of tolerance. The delay is how long a finger must rest before the card lifts; the tolerance is how far it may drift in that time before dnd kit gives up and lets the browser scroll. Those two numbers are the whole dnd kit mobile scroll trade-off:

Setting	Too low	Too high
`delay`	a slow swipe lifts a card instead of scrolling	the drag feels broken, and it collides with the system long press (text selection, the iOS callout)
`tolerance`	a resting finger drifts a pixel and the drag never starts	a slow scroll can turn into a drag halfway through

Never use a tolerance of zero. The Touch sensor docs say that with zero, any movement during the delay aborts the drag, and a finger resting on glass always moves a little. Issue #1955, opened in March 2026 against the rewrite, reported drags that never started on some Android phones, mostly Samsung; in July 2026 the reporter traced it to a tolerance: 0 and fixed it with 5. The rewrite's PointerSensor gives touch a 250ms delay with 5px tolerance by default; our Kanban and Deal Pipeline use 250ms and 8px.

A long press needs feedback at the moment it fires, or people let go too early. The Kanban calls navigator.vibrate(10) in onDragStart when the activator event is a TouchEvent, and lifts the card with a small scale and a 2 degree tilt on a spring. The tick does nothing on an iPhone, because Safari on iOS has no Vibration API (caniuse, checked in October 2026; the web vibration API guide covers what an iPhone can do instead).

Where does touch-action go?

On the element that receives the listeners, with a value that depends on which sensor owns the finger. The docs recommend manipulation for the TouchSensor and none for the PointerSensor, and the browser reads the value when the touch starts: changing it after pointerdown or touchstart is ignored. Put it in the CSS, never in a drag start handler.

Drag surface	Sensor that owns the finger	`touch-action`	Tailwind v4
The whole card or row, long press	TouchSensor	`manipulation`	`touch-manipulation`
A grip button	either	`none`	`touch-none`
The scroll container	no sensor	leave it `auto`	nothing

manipulation keeps panning and pinch zoom and drops double-tap zoom; once the drag is active, the TouchSensor cancels touchmove itself. A long-press surface needs two more classes: select-none, so the press does not select the card's text, and [-webkit-touch-callout:none], so iOS does not open its callout. dnd kit already cancels contextmenu on the window while a touch is pending or dragging.

The Wingo UI List takes the grip route: a 32px button with touch-none whose hit area grows to 44px on coarse pointers (why 44px), so a swipe on the row still scrolls the page or opens its swipe actions.

Why does a drag cancel on iPhone when the page scrolls?

Because @dnd-kit/core cancels any pointer or touch drag on a window resize, and Safari on iOS fires resize when its toolbar collapses or expands as the document scrolls. Issue #686 traced it on iOS 15 in March 2022. It was closed in February 2026 as filed against the old version, not fixed: the resize listener is still in the 6.3.1 sensors, so the cancel still happens.

The fix is layout: keep the drag inside its own scroll container so the document does not move. Give the board or list a real height (h-dvh, or flex-1 min-h-0 in a full-height layout; see 100vh on mobile), overflow-y-auto for a list or overflow-x-auto for a board, and overscroll-contain so reaching the end does not hand the scroll to the page.

The container also decides what auto-scroll moves. dnd kit scrolls the item's scrollable ancestors, meaning elements with overflow set to auto or scroll, plus the document, when the pointer comes within 20% of their edge. A wrapper with overflow: hidden does not count, so a board clipped that way cannot auto-scroll to its hidden columns; the page scrolls instead, if it can. If a phone board uses scroll snap, pause it during the drag: the Kanban board is snap-x snap-mandatory with data-dragging:snap-none, so the auto-scroll can glide to the next column.

Try it at phone width (or in device mode): the Kanban shows one column at a time with the next one peeking, a swipe scrolls it, and a 250ms press lifts a card you can carry to the edge to reach the next column.

Live demo: Kanban. The original article embeds an interactive demo here (Long press a card to lift it, then carry it to the board's edge to reach the next column; a quick swipe still scrolls. With a mouse it lifts after 8px. Tab to a card and press Space to move it with the arrow keys). Try it live on wingo-ui.com or open the Kanban docs. Install: npx wingo-ui@latest add kanban

How do you make drag and drop accessible?

With two separate paths, and dnd kit gives you one of them. The KeyboardSensor covers keyboard users: by default Space or Enter lifts, the arrow keys move, Space, Enter or Tab drops and Escape cancels, while DndContext reads instructions and live announcements to screen readers. Write your own announcements, because the defaults read raw ids ("Picked up draggable item d02."). The Kanban passes keyboardCodes: { start: ["Space"], cancel: ["Escape"], end: ["Space", "Enter"] }, since Enter opens a card, and its own coordinateGetter sends Left and Right to the nearest card in the next column that accepts it.

The second path is for people who can tap but not drag, because of a tremor, a trackball or a head pointer. WCAG 2.2 success criterion 2.5.7 Dragging Movements (level AA) requires that dragging "can be achieved by a single pointer without dragging", and the W3C's explanation says keyboard equivalence alone does not meet it. One of its examples is the pattern a list needs: after a tap on an item, controls next to it move it up or down. For a board, the same idea is a menu that names the target column. The Kanban puts Move to first in every card's ⋯ menu, which opens as a bottom sheet on phones.

How do you build a sortable list that works on phones?

Combine everything above in one component: the useDragSensors hook, long-press rows, a list with its own scroller, named announcements and up and down buttons for the tap path. It also passes id={useId()} to DndContext. Without it, dnd kit numbers its aria-describedby ids with a module-level counter, the server and the browser can count differently, and React reports a hydration mismatch in Next.js.

Install the packages with npm i @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities lucide-react and the free Button with npx wingo-ui@latest add button, then save this as components/sortable-tasks.tsx, next to use-drag-sensors.ts:

"use client";

import { useId, useState } from "react";
import { DndContext, closestCenter, type Announcements, type DragEndEvent, type UniqueIdentifier } from "@dnd-kit/core";
import { SortableContext, arrayMove, useSortable, verticalListSortingStrategy } from "@dnd-kit/sortable";
import { CSS } from "@dnd-kit/utilities";
import { ArrowDown, ArrowUp } from "lucide-react";
import { Button } from "@/components/ui/button";
import { useDragSensors } from "./use-drag-sensors";

type Task = { id: string; title: string };

export function SortableTasks({ initial }: { initial: Task[] }) {
  const [tasks, setTasks] = useState(initial);
  const sensors = useDragSensors();
  // a stable id: dnd kit's own counter differs between the server and the browser
  const dndId = useId();

  const name = (id: UniqueIdentifier) => tasks.find((task) => task.id === id)?.title ?? "Task";
  const place = (id: UniqueIdentifier) => `position ${tasks.findIndex((task) => task.id === id) + 1} of ${tasks.length}`;
  const announcements: Announcements = {
    onDragStart: ({ active }) => `Picked up ${name(active.id)}.`,
    onDragOver: ({ active, over }) => (over ? `${name(active.id)} is at ${place(over.id)}.` : undefined),
    onDragEnd: ({ active, over }) => (over ? `Dropped ${name(active.id)} at ${place(over.id)}.` : `${name(active.id)} is back in place.`),
    onDragCancel: ({ active }) => `Canceled. ${name(active.id)} is back in place.`,
  };

  const move = (from: number, to: number) => {
    if (to < 0 || to >= tasks.length || from === to) return;
    setTasks((current) => arrayMove(current, from, to));
  };

  const onDragEnd = ({ active, over }: DragEndEvent) => {
    if (!over) return;
    move(tasks.findIndex((task) => task.id === active.id), tasks.findIndex((task) => task.id === over.id));
  };

  return (
    <DndContext
      id={dndId}
      sensors={sensors}
      collisionDetection={closestCenter}
      onDragEnd={onDragEnd}
      accessibility={{
        announcements,
        screenReaderInstructions: {
          draggable: "Press Space to pick up a task. Arrow keys move it, Space drops it, Escape cancels.",
        },
      }}
    >
      <SortableContext items={tasks} strategy={verticalListSortingStrategy}>
        {/* its own scroller: the drag scrolls this list, not the document, so Safari's toolbar stays put */}
        <ul className="flex max-h-[70dvh] flex-col gap-2 overflow-y-auto overscroll-contain p-1">
          {tasks.map((task, index) => (
            <TaskRow key={task.id} task={task} index={index} last={index === tasks.length - 1} onMove={move} />
          ))}
        </ul>
      </SortableContext>
    </DndContext>
  );
}

type TaskRowProps = { task: Task; index: number; last: boolean; onMove: (from: number, to: number) => void };

function TaskRow({ task, index, last, onMove }: TaskRowProps) {
  const { attributes, listeners, setNodeRef, setActivatorNodeRef, transform, transition, isDragging } = useSortable({
    id: task.id,
  });

  return (
    <li
      ref={setNodeRef}
      style={{ transform: CSS.Transform.toString(transform), transition }}
      data-dragging={isDragging || undefined}
      className="flex items-center gap-1 rounded-2xl bg-card ps-4 pe-1 shadow-raised data-dragging:relative data-dragging:z-10 data-dragging:shadow-floating"
    >
      {/* the label is the drag surface: a swipe scrolls the list, a 250ms press lifts the row */}
      <div
        ref={setActivatorNodeRef}
        {...attributes}
        {...listeners}
        className="flex min-h-12 flex-1 cursor-grab touch-manipulation select-none items-center text-sm outline-hidden [-webkit-tap-highlight-color:transparent] [-webkit-touch-callout:none] focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-ring"
      >
        {task.title}
      </div>
      {/* the same move with single taps (WCAG 2.5.7) */}
      <Button variant="ghost" size="icon" radius="full" aria-label={`Move ${task.title} up`} disabled={index === 0} onClick={() => onMove(index, index - 1)}>
        <ArrowUp />
      </Button>
      <Button variant="ghost" size="icon" radius="full" aria-label={`Move ${task.title} down`} disabled={last} onClick={() => onMove(index, index + 1)}>
        <ArrowDown />
      </Button>
    </li>
  );
}

A server page, such as app/tasks/page.tsx, can render it with plain data:

import { SortableTasks } from "@/components/sortable-tasks";

const tasks = [
  { id: "t1", title: "Send the New York lease to Emma Carter" },
  { id: "t2", title: "Book the photographer for Friday" },
  { id: "t3", title: "Review the Q4 budget" },
];

export default function TasksPage() {
  return <SortableTasks initial={tasks} />;
}

Then test on a real phone: device mode does not show the Safari toolbar, a real finger's drift or the system long press. Try every path with a screen reader on, too.

If you would rather not own this code for a plain list, the List has sortable rows built in: turn on sortable, then drag a row by its grip, or Tab to a grip and use Space and the arrow keys; Alt with Up or Down moves a focused row one step. It has no tap path for reordering, so for 2.5.7 add Move up and Move down entries to each row's actions menu (its ⋯ button is always visible on touch) and reorder your items in their handlers.

Live demo: List. The original article embeds an interactive demo here (Drag a row by its grip to reorder the inbox; a swipe on the row still scrolls. Tab to a grip and press Space, then the arrow keys, or press Alt with Up or Down on a focused row). Try it live on wingo-ui.com or open the List docs. Install: npx wingo-ui@latest add list

Is there a React kanban board that already works on phones?

Yes: the Wingo UI Kanban ships the touch, mouse and keyboard setup from this post, the Move to menu and the phone layout. npx wingo-ui@latest add kanban copies it and everything it imports into your project and installs its npm packages. The Kanban, List and Deal Pipeline are Pro components (pricing). For the other phone gestures, such as swipe actions and drag to dismiss, read the mobile-first React components guide. The React form components guide applies the same touch, keyboard and screen reader rules to every form control, and more tutorials like this one are in the component guides category.

Components in this post

Kanban (Pro): A board of columns and cards for pipelines, orders and tasks: drag with mouse, touch or keyboard, WIP limits, inline add and a phone layout. Install: npx wingo-ui@latest add kanban
List (Pro): Rows on a page for settings, contacts, inboxes and orders: iOS grouped panels, selection, row menus, swipe actions and drag to reorder. Install: npx wingo-ui@latest add list
Deal Pipeline (Pro): The sales pipeline: stages with weighted totals, a forecast summary, drag between stages with a lost reason, and a list view. Install: npx wingo-ui@latest add deal-pipeline

FAQ

Why is dnd kit not working on mobile?

DndContext uses the PointerSensor by default, and pointer events cannot stop the browser from scrolling, so a touch drag is canceled as soon as the page starts to pan. Either set touch-action: none on a drag handle, or let a TouchSensor with a 250ms delay own the finger, next to a pointer sensor that skips touch, so a long press lifts the item and a swipe still scrolls.

Can I use PointerSensor and TouchSensor together in dnd kit?

Not the stock PointerSensor. A touch fires pointerdown before touchstart, so the PointerSensor claims the finger and the TouchSensor's delay never runs; subclass PointerSensor with an activator that skips pointerType touch, or pair MouseSensor with TouchSensor.

What delay and tolerance should the dnd kit TouchSensor use?

Start with a 250ms delay and 5 to 8px of tolerance; the dnd kit rewrite uses 250ms and 5px as its touch default. Never set the tolerance to 0, because the docs say any movement during the delay then aborts the drag, and a resting finger always drifts a little.

Why does dnd kit cancel my drag on iPhone?

@dnd-kit/core cancels pointer and touch drags on a window resize, and Safari on iOS fires resize when its toolbar collapses or expands as the page scrolls. Keep the drag inside its own scroll container so the document never scrolls during a drag.

Is keyboard drag and drop enough for accessibility?

It covers keyboard users but not WCAG 2.2 success criterion 2.5.7 Dragging Movements, which asks for a way to do the same thing with single taps or clicks. Add a Move to menu or up and down buttons next to the drag.

Should I switch to @dnd-kit/react for mobile drag?

Not for touch alone. The legacy docs point to the new version, and its PointerSensor gives touch a 250ms delay with 5px tolerance by default, but as of October 2026 @dnd-kit/react is at 0.5.0, before 1.0, with a different API. On @dnd-kit/core 6.3.1, the sensor setup in this post fixes touch drag.

This article was originally published on the Wingo UI blog: dnd kit Mobile: Touch Drag That Lets the Page Scroll. The original has the live, interactive demos and is kept up to date.

React Use Mobile Hook: SSR-Safe, No Hydration Mismatch

Serban Dan Rusu — Sun, 01 Nov 2026 15:00:00 +0000

TL;DR

A React use mobile hook returns false on the server because the server has no screen: it renders the HTML before any browser reports a width, and hydration has to repeat that guess. Switch visible layout with CSS breakpoints, which apply at first paint, and keep the hook for behavior after an interaction, such as opening a bottom sheet instead of a dialog. Build the hook on useSyncExternalStore with a server snapshot, so hydration matches and every later mount reads the real value on its first render.

Sooner or later, a Next.js app that has to work on phones grows a React use mobile hook: a useIsMobile() that returns true below 768px, copied from a starter or from shadcn/ui. It works in the browser, then surprises you three ways: it returns false on the server, a careless version throws a hydration error, and a phone can briefly see the desktop version of whatever the hook controls. This tutorial explains where each one comes from, which jobs belong to CSS breakpoints, and how to write an SSR-safe media query hook on useSyncExternalStore that hydrates cleanly.

Why is useIsMobile false on the server?

Because the server has no screen. React renders the HTML before any browser has reported a width, so a hook that reads matchMedia has nothing to read and must return a fixed guess. In the Next.js App Router the gap is wider still: a page that uses no request-time APIs is prerendered once at build time, with no request and no visitor at all.

The guess itself is harmless. The trouble is hydration: the first client render has to produce the same markup as the server, so the browser repeats the guess, and the value may only change after hydration. On a phone, the server's answer stays on screen from the first paint until the JavaScript has downloaded, parsed and hydrated, and on a slow connection that takes a while. Anything visible that depends on the hook is wrong for that whole window.

So the useful question is which jobs can live with a guess for that window.

Why does a useIsMobile hook cause a hydration mismatch?

Only when it reads window during render: the browser's first render then disagrees with the server's HTML. Search for a React is mobile hook and you find three shapes, and only the first one does that. We server-rendered each one with renderToString from React 19.3, hydrated it with hydrateRoot in Chromium at 390px through Playwright, and mounted a second copy 300ms later, the way a dialog, a lazy panel or a client-side route mounts after hydration:

Pattern	Hydration at 390px	First render of a later mount
`typeof window` check in render	Text: an error, the tree is rebuilt on the client. A class: no error, the server's class stays	`true`
`useState` + `useEffect`	No error: `false`, then `true` after the effect	`false`, then `true`
`useSyncExternalStore` with a server snapshot	No error: `false`, then `true` right after hydration	`true`

The first shape is the obvious one:

// wrong: the server says false, a phone says true during hydration
const isMobile = typeof window !== "undefined" && matchMedia("(max-width: 767.98px)").matches;

When the hook changes text, React 19 reports "Hydration failed because the server rendered text didn't match the client" and rebuilds that tree on the client, which throws away the work SSR did. The Next.js hydration error page lists this exact check as a common cause.

When the hook only picks a className, nothing fails, and that is worse. In development React 19 logs "A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up." A production build logs nothing. In our test the phone kept class="desktop" after hydration in both builds, and nothing corrects it while the value stays the same.

The second shape is the shadcn use-mobile hook that ships with the shadcn/ui Sidebar. As of October 2026 its source keeps undefined in state, measures in an effect and returns !!isMobile:

const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)

React.useEffect(() => {
  const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
  // ...subscribes to mql, then:
  setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
}, [])

return !!isMobile

It never mismatches, because every first render returns false. The catch is the word every: a component that mounts long after hydration also renders as a desktop once, then corrects itself in the effect. An autoFocus={!isMobile} on a field in that component is true on the first commit, and React focuses the field during that commit, so a phone can still get the keyboard you meant to avoid.

The shadcn Sidebar gets away with the false start for a good reason. The desktop markup it renders on the server carries hidden md:block, so a phone never sees it, and on a phone the correction swaps in a Sheet that stays closed until someone opens it. That is the pattern to copy, and the next section spells it out.

When should you use CSS breakpoints instead of a hook?

For everything visible before the first interaction. CSS media queries apply at first paint, before any JavaScript runs, so they are already right in the server's HTML. Render both versions and let a breakpoint hide one:

// app/orders/page.tsx: a server component, no hook to correct
import { getOrders } from "@/lib/orders";
import { OrderCard } from "./order-card";
import { OrderRow } from "./order-row";

export default async function OrdersPage() {
  const orders = await getOrders();
  return (
    <>
      <ul className="flex flex-col gap-2 md:hidden">
        {orders.map((order) => (
          <OrderCard key={order.id} order={order} />
        ))}
      </ul>
      <table className="hidden w-full md:table">
        <tbody>
          {orders.map((order) => (
            <OrderRow key={order.id} order={order} />
          ))}
        </tbody>
      </table>
    </>
  );
}

Both trees are in the DOM, which costs little for a nav or a page of 20 rows. When the switch depends on the space a component gets rather than the window, Tailwind v4's @container and @md: variants do it in CSS with no hook at all.

Keep the hook for decisions that start after the person does something, or that never show on the first paint:

which overlay opens: a bottom sheet below 768px, a popover or a dialog above it
the edge a panel slides in from
whether a field takes focus when a panel opens, since focusing it on a phone pops the keyboard over the content
where a click goes: a full page on a phone, a side panel next to the list on desktop

A closed overlay renders only its trigger, and the trigger is usually the same button in both modes, so the hook can switch the overlay freely. The shadcn responsive dialog tutorial builds that switch for a dialog, and the mobile-first React components guide applies the same rule across a whole component library.

How do you write an SSR-safe useMediaQuery hook?

Read the query through useSyncExternalStore, React's API for values that live outside React, and give it a server snapshot. That is the whole fix for useMediaQuery SSR problems:

// hooks/use-media-query.ts
import { useCallback, useSyncExternalStore } from "react";

// the complement of Tailwind's md: variant, in the same unit
export const MOBILE_QUERY = "(width < 48rem)";

const lists = new Map<string, MediaQueryList>();

function getList(query: string) {
  let list = lists.get(query);
  if (!list) {
    list = window.matchMedia(query);
    lists.set(query, list);
  }
  return list;
}

export function useMediaQuery(query: string, serverFallback = false) {
  // stable per query, or React unsubscribes and subscribes again on every render
  const subscribe = useCallback(
    (onChange: () => void) => {
      const list = getList(query);
      list.addEventListener("change", onChange);
      return () => list.removeEventListener("change", onChange);
    },
    [query],
  );
  return useSyncExternalStore(
    subscribe,
    () => getList(query).matches,
    // the server and the hydration render
    () => serverFallback,
  );
}

export function useIsMobile() {
  return useMediaQuery(MOBILE_QUERY);
}

// the same check in event handlers and effects; false on the server
export function matchesMedia(query: string) {
  return typeof window !== "undefined" && getList(query).matches;
}

Here is what React does with it:

Server and hydration. React calls the third function, so the server HTML and the hydration render agree. Leave it out and the React docs are blunt: "rendering the component on the server will throw an error."
Right after hydration. Once the effects run, React compares the server snapshot with the browser's answer and, when they differ, re-renders synchronously. That is the false, then true in the table above.
Every later mount. React calls the second function during the first render, so a sheet that opens on a phone renders as a phone from its first frame.
Updates. A MediaQueryList fires change only when the query flips, so dragging the window edge costs no renders until it crosses the breakpoint, unlike a resize listener. The lists are cached per query because matches is read on every render.

If the shadcn Sidebar added hooks/use-mobile.ts to your project, point that file at the new hook. The Sidebar keeps its import, and its hidden md:block desktop markup now flips at the same width as the hook:

// hooks/use-mobile.ts
import { MOBILE_QUERY, useMediaQuery } from "@/hooks/use-media-query";

export const useIsMobile = () => useMediaQuery(MOBILE_QUERY);

Event handlers do not need the hook at all. Read the query at the moment of the click:

// app/orders/use-open-order.ts
"use client";

import { useRouter } from "next/navigation";
import { useState } from "react";
import { MOBILE_QUERY, matchesMedia } from "@/hooks/use-media-query";

export function useOpenOrder() {
  const router = useRouter();
  const [selected, setSelected] = useState<string | null>(null);

  function openOrder(id: string) {
    // phones get a full page, desktops a panel next to the list
    if (matchesMedia(MOBILE_QUERY)) router.push(`/orders/${id}`);
    else setSelected(id);
  }

  return { selected, openOrder };
}

Which serverFallback should you pass?

The answer whose mistake costs least during the hydration window. For useIsMobile, false is usually right, because the decisions it drives start after a tap and by then the real value is in. For a query that changes something visible, pick the answer that works on every device. With (hover: hover) that is false: the server renders the always-visible version of a control, and a mouse user gets the hover polish a moment later.

Should the query use px or rem?

Use the unit of your CSS breakpoints. Tailwind v4 defines --breakpoint-md: 48rem, and our build compiles md: to @media (min-width: 48rem). Media Queries Level 4 says relative units in media queries are "based on the initial value", so 48rem follows the default font size set in the visitor's browser and ignores your html { font-size }. A hook written in px does not move with it.

We checked this in Chromium through Playwright, with a 900px window and the default font size set to 20px. (min-width: 48rem) stopped matching, so Tailwind showed the phone layout, while (max-width: 767.98px) did not match either, so a px hook still reported a desktop. (width < 48rem) matched, in step with the CSS. Range syntax also retires the .98px trick that Bootstrap's docs explain with "viewports with fractional widths". As of October 2026, MDN's compatibility data lists range syntax from Chrome 104, Firefox 102 and Safari 16.4.

Breakpoints are tokens like colors and radii, so keep them in one place: the Tailwind v4 design tokens guide shows how to layer them. A caveat about our own code: as of October 2026 the MOBILE_QUERY in Wingo UI is still (max-width: 767.98px), so it has the gap described above. With a 20px default font size, md: classes switch at 960px while the Drawer and the Sheet, which call useIsMobile(), switch at 768px. In your own components, call useMediaQuery("(width < 48rem)") where the hook and your classes have to agree.

Can Next.js detect mobile on the server?

It can guess from request headers, and only on routes rendered per request. Most ways to make React detect mobile or desktop on the server read the User-Agent header. Next.js parses it with userAgent() from next/server, whose device.type is "mobile", "tablet" and a few others, or undefined for desktop browsers. Pass the guess down as the server snapshot and hydration still matches, because the prop travels with the page:

// app/orders/page.tsx
import { headers } from "next/headers";
import { userAgent } from "next/server";
import { OrdersScreen } from "./orders-screen";

export default async function OrdersPage() {
  const { device } = userAgent({ headers: await headers() });
  return <OrdersScreen phoneGuess={device.type === "mobile"} />;
}

// app/orders/orders-screen.tsx
"use client";

import { MOBILE_QUERY, useMediaQuery } from "@/hooks/use-media-query";

export function OrdersScreen({ phoneGuess }: { phoneGuess: boolean }) {
  // the server and the hydration render both use the guess, then the real value takes over
  const isMobile = useMediaQuery(MOBILE_QUERY, phoneGuess);
  return <p>{isMobile ? "Tap an order to open it" : "Select an order to see it on the right"}</p>;
}

Know the cost before you add it:

Dynamic rendering. headers() is a request-time API, so the page renders on every request instead of once at build time, and any shared cache has to vary by user agent. With Cache Components turned on, the read also has to sit inside a <Suspense> boundary, or next build fails.
It names a device. The header stays the same for a desktop browser narrowed to 600px, a tablet app in split screen and a phone turned to landscape, so it cannot tell you the window width. Since Safari 13, Safari on iPad sends the same user agent as Safari on macOS by default, so most iPads read as desktops.
Client hints cover Chromium only. Sec-CH-UA-Mobile arrives without opting in, but as of October 2026 MDN's compatibility data lists it in Chrome and Edge and not in Firefox or Safari.

It pays off on app pages that are dynamic anyway, such as a signed-in dashboard, and rarely on marketing pages you want served from a CDN.

How do the Wingo UI Sheet and Drawer use the hook?

Only for behavior, and their closed state renders the same markup at every width. The free useMediaQuery hook is built the same way, with the same serverFallback parameter, plus useIsMobile, useIsTouch for (pointer: coarse), useBreakpoint and matchesMedia. Resize this window across 768px, or open the page on a phone:

Live demo: useMediaQuery. The original article embeds an interactive demo here (Resize the window across 768px: the useIsMobile() card and the (width < 48rem) card flip together at the default font size, and the ruler moves to the widest Tailwind breakpoint that matches). Try it live on wingo-ui.com or open the useMediaQuery docs. Install: npx wingo-ui@latest add use-media-query

The Drawer calls useIsMobile() in its root. Phones always get the draggable sheet; from 768px the desktop prop picks a centered sheet, a side panel or a dialog. Its trigger is the same Radix Dialog trigger in every mode, so the server's guess changes nothing on screen, and the open state lives in the root, so a tablet rotated across 768px keeps the drawer open.

Live demo: Drawer. The original article embeds an interactive demo here (Tap Filters: below 768px the drawer slides up as a sheet you can drag down to close; on a wider screen the same component opens a centered dialog). Try it live on wingo-ui.com or open the Drawer docs. Install: npx wingo-ui@latest add drawer

The Sheet does the same for side panels. mobileSide="bottom" turns a filter panel from the right into a bottom sheet on phones, and the side only matters once the sheet is open:

import { SlidersHorizontal } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Sheet } from "@/components/ui/sheet";

export function OrderFilters() {
  return (
    <Sheet
      side="right"
      mobileSide="bottom"
      title="Filters"
      description="Status, date and amount"
      trigger={
        <Button variant="soft" leftIcon={<SlidersHorizontal />}>
          Filters
        </Button>
      }
    >
      <p className="text-sm text-muted-foreground">Pick the orders you want to see.</p>
    </Sheet>
  );
}

What should you do next?

Paste the hook above into hooks/use-media-query.ts, or install ours with npx wingo-ui@latest add use-media-query. Then search your codebase for useIsMobile and sort every call: visible layout moves to md: classes, behavior stays on the hook. More posts on the same stack live in Next.js and Tailwind CSS.

Components in this post

useMediaQuery (Free): SSR-safe hooks for media queries, phone widths, touch screens and the current Tailwind breakpoint. Install: npx wingo-ui@latest add use-media-query
Sheet (Free): A panel that slides in from any edge on a spring: filters, a cart, an inspector or the phone navigation menu, swipeable to close on touch. Install: npx wingo-ui@latest add sheet
Drawer (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: npx wingo-ui@latest add drawer

FAQ

Why does useIsMobile return false on the server?

The server renders the HTML before any browser reports a screen width, so the hook has nothing to measure and returns a fixed guess. Hydration has to repeat that guess, and the real value arrives right after it.

Does the shadcn useIsMobile hook cause a hydration mismatch?

No. The shadcn use-mobile hook keeps undefined in state and measures the screen in an effect, so its first render returns false on the server and in the browser alike. The cost is that a component mounted after hydration also renders as a desktop once, until the effect corrects it.

How do I fix a hydration mismatch caused by useMediaQuery?

Stop reading window during render and read the query through useSyncExternalStore, with a getServerSnapshot that returns the same value on the server and during hydration. React then corrects the value right after hydration, with no mismatch.

Can Next.js detect a mobile device on the server?

It can guess from the User-Agent header with userAgent() from next/server, which makes the route render per request. The header names a device and says nothing about the viewport width, so use the guess as the server snapshot only and keep layout in CSS.

Why does my useIsMobile hook disagree with Tailwind's md breakpoint?

Tailwind v4 breakpoints are in rem (md is 48rem), and media queries resolve rem from the browser's default font size, while many hooks, shadcn's included, hard-code 768px. When a visitor raises that font size the two disagree; write the hook's query as (width < 48rem) and both flip at the same width.

Is the Wingo UI useMediaQuery hook free?

Yes. useMediaQuery, useIsMobile and the rest of the hook file are free, and so are the Sheet and the Drawer that use it. Install the hook with npx wingo-ui@latest add use-media-query.

This article was originally published on the Wingo UI blog: React Use Mobile Hook: SSR-Safe, No Hydration Mismatch. The original has the live, interactive demos and is kept up to date.

React Wheel Picker: iOS Wheels for Times and Dates

Serban Dan Rusu — Sun, 01 Nov 2026 07:00:00 +0000

TL;DR

A React wheel picker that feels native lets the browser do the scrolling: a scroll-snap list brings the phone's own momentum and rubber band, each row is turned on a 3D cylinder from scrollTop in one animation frame, and the value commits once, when the wheel comes to rest. Use wheels for times, durations and birth dates on phones, keep a typed field on desktop, and give mouse drag, the scroll wheel and the keyboard their own paths. Wingo UI's Pro Picker Wheel and Time Picker ship all of this, with a bottom sheet below 768px.

You want a React wheel picker because a phone user should not type 14:30 on a keyboard that covers half the form, and paging a calendar back 36 years to a birth date is worse. The hard part is the feel: the React wheel packages we checked replace the browser's scrolling with their own touch physics. This guide builds the wheel on a native snapping scroller with rows turned on a 3D cylinder, then covers mouse and keyboard paths, the time and date fields built on it, and the pitfalls. How wheel pickers compare across libraries is in our best React component library for mobile comparison.

When is a wheel picker the right control?

When the list is medium to long, ordered, and the user can guess what is hidden: hours, minutes, durations, quantities, a birth year. Apple's Human Interface Guidelines for pickers say to "consider using a picker to offer medium-to-long lists of items", to prefer a pull-down button for "a fairly short list of choices", and a list or table for "a very large set of items". It also suggests minute steps that divide 60 evenly, such as quarter hours.

On the web that gives four rules:

Two to five options: a Segmented Control, so every option is visible.
12 hours, 60 minutes, 1 to 99 items, the years since 1920: a wheel.
Hundreds of unordered names (countries, products): a searchable Select. A wheel only jumps to a typed prefix.
A date near today (a delivery, a booking): a calendar, because the weekday matters.

Why build a wheel on a native snapping scroller?

Because then the finger, the momentum and the rubber band at the ends are the phone's own, and a trackpad or a mouse wheel turns it with no extra code. A search for "ios picker web" in October 2026 mixed a Mendix widget, React Native packages and Flutter's CupertinoPicker in with the web answers. The two React DOM packages we found both run their own physics:

Package (as of October 2026)	License, last release	How it moves
@ncdai/react-wheel-picker 1.2.3	MIT, August 23, 2026	own touch, mouse and wheel handlers; rows on a 3D cylinder with CSS transforms
react-mobile-picker 1.2.0	MIT, August 3, 2025	own `touchmove` handler and `translate3d`; mouse wheel off by default

Both work. @ncdai/react-wheel-picker, which also handles arrows, Home / End and type-ahead, is the better pick if you want a free, unstyled wheel and will build the field yourself. Its feel is tuned through dragSensitivity and scrollSensitivity; a native scroller decelerates like every other list on that phone.

The native recipe has three parts. The list scrolls with scroll-snap-type: y mandatory, every row snaps to the center, and two rows of padding let the first and last rows reach it. One requestAnimationFrame per scroll reads scrollTop and writes rotateX and opacity straight to the rows, never through React state. And the value commits once, at rest: on scrollend, which MDN lists from Chrome 114, Firefox 109 and Safari 26.2, with a 120ms idle timer for older Safari.

"use client";

import { useEffect, useRef } from "react";

const ROW = 44; // five rows in a 220px window

export function MiniWheel({ options, onSettle }: { options: string[]; onSettle: (value: string) => void }) {
  const listRef = useRef<HTMLDivElement>(null);
  const settleRef = useRef(onSettle);
  useEffect(() => {
    settleRef.current = onSettle;
  });

  useEffect(() => {
    const list = listRef.current;
    if (!list) return;
    const rows = Array.from(list.firstElementChild?.children ?? []) as HTMLElement[];
    let frame = 0;
    let idle: ReturnType<typeof setTimeout> | undefined;
    let last = "";

    // the turn and the fade go straight to the rows, never through React state
    const paint = () => {
      frame = 0;
      const pos = list.scrollTop / ROW;
      rows.forEach((row, i) => {
        const d = i - pos;
        row.style.transform = `perspective(400px) rotateX(${Math.max(-55, Math.min(55, -d * 20))}deg)`;
        row.style.opacity = String(Math.max(0.35, 1 - Math.min(Math.abs(d), 3) * 0.22));
      });
    };
    // one commit when the wheel is at rest, never one per row passed
    const settle = () => {
      clearTimeout(idle);
      const value = options[Math.round(list.scrollTop / ROW)];
      if (value !== undefined && value !== last) settleRef.current((last = value));
    };
    const onScroll = () => {
      if (!frame) frame = requestAnimationFrame(paint);
      clearTimeout(idle);
      idle = setTimeout(settle, 120); // Safari before 26.2 has no scrollend
    };

    paint();
    list.addEventListener("scroll", onScroll, { passive: true });
    list.addEventListener("scrollend", settle);
    return () => {
      list.removeEventListener("scroll", onScroll);
      list.removeEventListener("scrollend", settle);
      cancelAnimationFrame(frame);
      clearTimeout(idle);
    };
  }, [options]);

  return (
    <div ref={listRef} className="h-[220px] snap-y snap-mandatory overflow-y-scroll overscroll-contain [scrollbar-width:none]">
      <div className="py-[88px]">
        {options.map((option) => (
          <div key={option} className="flex h-11 snap-center items-center justify-center text-xl tabular-nums">
            {option}
          </div>
        ))}
      </div>
    </div>
  );
}

That is the core of the Wingo UI Picker Wheel. The sketch misses a starting value, disabled rows, looping, every input that is not a finger, and wheels mounted while hidden.

How do mouse and keyboard users turn the wheel?

A mouse wheel and a trackpad scroll it natively; dragging and keys need their own code. In the Picker Wheel only a mouse goes through pointer events: past 8 pixels of movement, snapping turns off and scrollTop follows the pointer. On release, a motion inertia animation continues from the measured velocity, and its modifyTarget rounds the landing point to a row. A click on a visible row glides it to the center.

Each column is one Tab stop with role="listbox". ArrowUp and ArrowDown move a row, PageUp and PageDown five, Home and End jump to the ends, typing jumps to the next option that starts with the text ("19", then "199" on a year wheel), and ArrowLeft and ArrowRight change column. aria-activedescendant points at the centered option, which carries aria-selected. The focus ring hugs the center row, where the edge fade cannot hide it.

What props does the Picker Wheel need?

columns (or options for a single wheel), a value and onValueChange. Everything else has a default:

"use client";

import { useState } from "react";
import { PickerWheel, pickerRange } from "@/components/ui/picker-wheel";

const hours = pickerRange(0, 12);
const minutes = pickerRange(0, 59, { pad: 2 });

export function CallDuration() {
  const [duration, setDuration] = useState(["1", "25"]);
  return (
    <PickerWheel
      aria-label="Call duration"
      value={duration}
      // once per settle, with every column's value and the id of the column that moved
      onValueChange={(value) => setDuration(value)}
      columns={[
        { id: "hours", label: "h", options: hours, align: "end" },
        { id: "minutes", label: "min", options: minutes, align: "start", loop: true },
      ]}
    />
  );
}

The props worth knowing:

onValueChange fires once per settle, never per row passed, so it is safe to save from it.
loop (on the wheel or per column) wraps 59 back to 00: the column renders extra copies and jumps silently to the middle one at rest. Only the middle copy has role="option".
size sets 36, 44 or 52px rows; visibleRows (odd, default 5) makes the wheel 220px tall at md; perspective tilts rows 20, 10 or 0 degrees each (ios, subtle, flat).
A disabled option is struck through, and a wheel that lands on one glides on to the nearest enabled row: pickerRange(36, 46, { disabled: (n) => n === 38 }) for a sold-out shoe size.
haptics plays a selection tick each time a finger, a mouse drag or the scroll wheel brings a new row to the center, never for keys. It works on Chrome for Android; why a scroll cannot tick on an iPhone is in our web vibration API guide.

PickerWheelField puts the same wheels in a form field: a bottom sheet with Done and Cancel below 768px, a popover that applies live on desktop.

How do you build a React time picker wheel that still types on desktop?

Use the Time Picker, which switches by width. Below 768px the field is read-only with inputMode="none", so no keyboard opens, and a tap opens a bottom sheet with hour and minute wheels. From 768px up it is a text input that reads "1430", "2:30pm" or "2p", steps minutes with ArrowUp and ArrowDown, and opens a panel of columns on click. The value is always "HH:mm" in 24 hours:

"use client";

import { useState } from "react";
import { TimePicker } from "@/components/ui/time-picker";

const lunchBreak = (time: string) => time >= "13:00" && time < "14:00";

export function PickupTime() {
  const [time, setTime] = useState("11:30");
  return (
    <TimePicker
      label="Pickup time"
      name="pickup"
      locale="en-US"
      min="09:00"
      max="18:00"
      minuteStep={15}
      disabledTimes={lunchBreak}
      value={time}
      onValueChange={setTime}
    />
  );
}

Live demo: Time Picker. The original article embeds an interactive demo here (Type 2:30pm or 1430 and press Enter, or click the field for the columns; at phone width a tap opens the wheels in a bottom sheet, and the lunch hour stays blocked either way). Try it live on wingo-ui.com or open the Time Picker docs. Install: npx wingo-ui@latest add time-picker

The sheet edits a draft: Done commits it, and dragging the sheet away keeps the old time. Times outside min and max or blocked by disabledTimes are disabled rows on the wheels too.

Should a date be a wheel or a calendar?

A wheel for a date the user knows by heart and that sits far from today, like a birth date: three flicks instead of paging through years. A calendar for dates near today, where the weekday matters. That is why the Date Picker opens a calendar, in a bottom sheet on phones.

For the birth date, useDateWheel is a React date wheel picker in one hook: day, month and year columns in the locale's order (month, day, year for en-US), month names in that language, days that follow the month (February 29 only in leap years) and years between min and max. Values are ISO dates such as "1990-05-17".

Live demo: Picker Wheel. The original article embeds an interactive demo here (Flick the month, the day or the year, drag them with a mouse, or Tab to the year and type 1985: the date and the age under the wheel update when it comes to rest). Try it live on wingo-ui.com or open the Picker Wheel docs. Install: npx wingo-ui@latest add picker-wheel

For the wheel on phones and a typed field on desktop, render both and switch with CSS, so the server HTML matches the first paint (the mobile-first React components guide explains why a useIsMobile check would flash). One ISO string feeds both:

"use client";

import { useState } from "react";
import { DatePicker } from "@/components/ui/date-picker";
import { PickerWheelField, useDateWheel } from "@/components/ui/picker-wheel";
import { formatDate, fromISODate, toISODate } from "@/lib/date-utils";

export function BirthdayField({ initial }: { initial: string }) {
  const [birthday, setBirthday] = useState(initial); // "1990-05-17"
  const [today] = useState(() => new Date());
  const wheel = useDateWheel({ value: birthday, onValueChange: setBirthday, locale: "en-US", min: "1920-01-01", max: toISODate(today) });

  return (
    <>
      {/* phones: three wheels in a bottom sheet, Done to commit */}
      <div className="md:hidden">
        <PickerWheelField
          label="Date of birth"
          {...wheel}
          formatValue={() => formatDate(fromISODate(birthday), "en-US", { dateStyle: "long" })}
        />
      </div>
      {/* 768px and up: type 05171990, or open the calendar */}
      <div className="hidden md:block">
        <DatePicker
          label="Date of birth"
          locale="en-US"
          max={today}
          clearable={false}
          value={fromISODate(birthday)}
          onValueChange={(date) => date && setBirthday(toISODate(date))}
        />
      </div>
      <input type="hidden" name="birthday" value={birthday} />
    </>
  );
}

One catch: useDateWheel always holds a date (today when you pass none), so the field is never empty. That suits editing a profile; a required date that starts blank belongs in the Date Picker.

What goes wrong with a wheel picker on a phone?

Most bugs come from the wheel's surroundings. The Picker Wheel handles these, and you will meet them if you build your own:

The sheet steals the drag. A wheel at its first row hands a downward drag to the drawer. The columns carry data-vaul-no-drag, and overscroll-behavior: contain keeps a hard flick from scrolling the page.
A wheel mounted while hidden. Inside a closed sheet the list has no height, so setting scrollTop does nothing. A ResizeObserver scrolls to the value once the list has a size.
Committing per row. Saving on every row that passes floods your API and fires validation mid-spin.
Reduced motion. With prefers-reduced-motion the rows stay flat and programmatic moves jump instead of gliding.
Feedback only in the tick. Desktop and iPhone users feel nothing, so the centered row and the field text must carry the value.

Where should you start?

Open this page on your phone and flick the two demos above. The Picker Wheel, Time Picker and Date Picker are part of Wingo UI Pro; with a Pro account signed in through npx wingo-ui@latest login, npx wingo-ui@latest add picker-wheel copies the component and everything it imports into your project. A React wheel picker component is one piece of a phone-friendly form; the other patterns are in Mobile UI in React.

Components in this post

Picker Wheel (Pro): The iOS wheel picker for the web: columns that spin with native momentum and click into place on a 3D cylinder, inline or as a field. Install: npx wingo-ui@latest add picker-wheel
Time Picker (Pro): A time-of-day field to type into or pick from columns, with 12 / 24 hours by locale, minute steps, limits and iOS wheels on phones. Install: npx wingo-ui@latest add time-picker
Date Picker (Pro): A date field to type in your locale or pick from a calendar popover, with presets, limits and an optional time; a sheet on phones. Install: npx wingo-ui@latest add date-picker

FAQ

Is there an iOS-style wheel picker for React web apps?

Yes. As of October 2026 the open source options are @ncdai/react-wheel-picker (1.2.3, MIT) and react-mobile-picker (1.2.0, MIT), which both run their own touch physics. Wingo UI's Picker Wheel (Pro) scrolls natively and adds a form field that opens a bottom sheet on phones, a date hook and haptic ticks.

Should I use input type=time instead of a wheel picker?

Use the native input when its look and behavior are good enough, because it costs nothing and is accessible by default. You cannot style the picker it opens, it differs between browsers and OS versions, and it cannot show blocked times such as a lunch break, which is when a custom wheel earns its code.

How do I make a wheel picker loop around in React?

Render the options several times and jump back to the middle copy whenever the wheel comes to rest, which looks identical. In the Wingo UI Picker Wheel, loop on the wheel or on one column does this, with at least 40 rows on each side of the middle copy so a hard flick never reaches the end.

Does a web wheel picker vibrate on iPhone?

No. Safari has no Vibration API, and the iPhone's one web haptic, the tick of a native switch, plays only for a tap, never for a scroll. On Chrome for Android the Picker Wheel ticks each time a new row reaches the center.

Is the Wingo UI Picker Wheel free?

No. The Picker Wheel, Time Picker and Date Picker are Pro components; the Drawer and Field they build on are free. Pro costs $8 a month, $80 a year or $150 once.

This article was originally published on the Wingo UI blog: React Wheel Picker: iOS Wheels for Times and Dates. The original has the live, interactive demos and is kept up to date.

React Segmented Control: iOS Thumb, Drag and When to Use It

Serban Dan Rusu — Sat, 31 Oct 2026 15:00:00 +0000

TL;DR

A React segmented control is a radio group drawn as a row of 2 to 5 segments with a raised thumb on the selected one: one tab stop, arrow keys that move and select, and a 44px height on touch screens. Use it when the choice changes the content already on screen (a time range, a view, units); use Tabs when it swaps in a different panel, a Toggle Group when several options can be on, and radio cards when each option needs a description. The free Wingo UI Segmented Control adds the iOS details: a spring thumb you can drag sideways with a finger, while a vertical swipe still scrolls the page.

A React segmented control is the row of two to five options with a raised thumb under the selected one, the control iOS uses to pick the time range of the charts in the Health app. Search for an iOS segmented control web component and most results are React Native packages, and shadcn/ui ships none as of October 2026. This guide covers what the web version has to get right (the thumb, touch, keyboard and radio semantics), then the decision that matters more: when Tabs, a Toggle Group or radio cards are the better control. The examples use the free Segmented Control from Wingo UI, the library we build, so we are not neutral; outside facts link to their sources.

What is a segmented control, in web terms?

It is a radio group with a different look. Each segment is one option, exactly one is selected, and selecting one applies at once without a submit button. Apple's Human Interface Guidelines describe it as a way to offer "closely related choices that affect an object, state, or view." Material Design 3 has a close relative, the segmented button, so you also see the control searched as a React segmented button.

That framing settles the implementation: the markup should be a radiogroup with radio items, the WAI-ARIA radio group pattern defines the keyboard, and a name should make it submit like native radios. The thumb, the spring and the drag sit on top of that.

How do you add a segmented control in React?

Install it, pass options, and either let it hold its own value or control it:

npx wingo-ui@latest add segmented-control

"use client";

import { useState } from "react";
import { SegmentedControl, type SegmentedControlOption } from "@/components/ui/segmented-control";

const periods: SegmentedControlOption[] = [
  { value: "day", label: "Day" },
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
];

export function SalesPeriod() {
  const [period, setPeriod] = useState("week");

  return (
    <SegmentedControl
      aria-label="Period"
      options={periods}
      value={period}
      onValueChange={setPeriod}
      fullWidth
    />
  );
}

Each option takes value, label, and optionally icon, badge (a number renders a count that hides at 0), tooltip and disabled. The props that change the look are size (sm, md or lg, a 32, 40 or 48px track), radius, tone (default neutral, a white thumb like iOS that turns a lifted gray in dark mode) or any CSS color, and dividers, the hairlines between unselected segments. Leave defaultValue out and it starts on the first enabled option.

Live demo: Segmented Control. The original article embeds an interactive demo here (Tap or click Month, then press the thumb and slide it sideways: the value follows your finger and the sales total updates. With the keyboard, Tab in and use the arrow keys). Try it live on wingo-ui.com or open the Segmented Control docs. Install: npx wingo-ui@latest add segmented-control

If you came for a React segmented control Tailwind recipe, the whole look is Tailwind v4 utilities on design tokens, and every inner part takes classes through classNames (item, thumb, icon, label, badge, divider). App-wide defaults go through the free UIProvider: <UIProvider defaults={{ "segmented-control": { radius: "full" } }}> rounds every segmented control in the app.

What makes it feel like the iOS control?

Three details: the thumb moves on a spring instead of a linear tween, it follows the finger, and it never steals a scroll.

The thumb animates transform only. It is rendered inside the selected segment, so CSS sizes it at rest. When the value changes, it measures the box it is leaving, jumps there as a transform and springs back to zero offset using the snappy spring from lib/motion (stiffness 500, damping 32). Animating left and width would recalculate layout on every frame; a transform stays on the compositor. Its corner radius is divided by the current scale, so a thumb stretching between a short and a long label keeps round corners. A change mid-flight starts from where the thumb is on screen and keeps its speed.

It answers the finger. Pressing the thumb dips it to 96%. Keep holding and slide sideways and the value follows the segment under your finger, then settles where you let go. The hairlines next to the thumb fade out, like on iOS.

A vertical swipe still scrolls the page. The track sets touch-action: pan-y, so the browser keeps vertical scrolling, and the code waits for 8px of movement before deciding what the gesture is. This is the part to copy if you build your own, trimmed from the component:

// track: className="touch-pan-y"; drag.current is recorded on pointerdown over the thumb, SLOP is 8
function handlePointerMove(event: React.PointerEvent<HTMLDivElement>) {
  const state = drag.current;
  if (!state || state.id !== event.pointerId) return;
  if (!state.active) {
    const dx = Math.abs(event.clientX - state.x);
    const dy = Math.abs(event.clientY - state.y);
    // vertical first: a page scroll, let the browser have it
    if (dy > SLOP && dy > dx) return endPress();
    if (dx <= SLOP) return;
    state.active = true;
    event.currentTarget.setPointerCapture(event.pointerId);
  }
  // pick the segment under clientX from rects measured on pointerdown
}

touch-action: none on the track would make the drag simpler and trap anyone who starts a scroll on the control. After a drag, the click that follows lands on the segment where the drag began, so the component swallows it; otherwise the value snaps back.

With reduced motion turned on, the thumb jumps to its new place and the press dip is off.

Is a segmented control accessible?

It is when the semantics are a radio group, and that comes almost free from Radix. The Segmented Control is built on @radix-ui/react-radio-group, so the track is a radiogroup, each segment a radio with aria-checked, and the whole control is a single tab stop. Left and Right (Up and Down too) move focus and select, which matches the APG rule for a radio group outside a toolbar. We added Home and End, disabled segments are skipped, and loop={false} stops the arrows at the ends. Mantine takes the same route: its SegmentedControl docs (v9.7.1, October 2026) say it "uses radio inputs under the hood."

Four things are on you:

A name. Pass aria-label, or aria-labelledby pointing at a visible heading; both land on the radiogroup.
Text for icons. Give icon options a label anyway. With iconOnly, it becomes the segment's aria-label and its tooltip, shown on hover, on keyboard focus and on a long press on touch.
A form name. Pass name and, inside a <form>, the selected value submits like native radios.
A non-drag path. WCAG 2.5.7 Dragging Movements (level AA) asks that anything done by dragging also work with a single pointer without dragging. Tapping a segment is that path, so keep it. Never make the drag the only way.

One trap if you build on Radix yourself: Radix checks the next radio only if the arrow key is still down when its deferred focus lands, so a very quick press (a screen reader, a remote, automation) can move focus without checking anything. The component selects on any focus that follows an arrow key, so a fast press still changes the value.

How should a segmented control behave on a phone?

It should be 44px tall on touch, share the width, and never flash gray on tap. The md size is a 40px track with a mouse and grows to 44px on coarse pointers (pointer-coarse:h-11). The sm size keeps its 32px look and gets an invisible hit area that reaches 44px; lg is 48px everywhere. The reasoning behind 44px, and the Tailwind variants that apply it only on touch, are in minimum touch target size for React and Tailwind.

fullWidth gives each segment an equal share of the container, the usual layout under a phone header. A segment with a long label keeps its natural width instead of truncating, and the others share what is left. Every segment carries touch-manipulation and a transparent -webkit-tap-highlight-color, so a quick second tap never zooms the page and iOS shows no gray flash. Set dir="rtl" and the layout, the arrow keys and the drag mirror.

The rest of the rules (sheets instead of popovers, safe areas, hover alternatives) are in the pillar on mobile-first React components, and the Mobile UI in React category collects every guide on the topic.

Segmented control vs tabs, a toggle group or radio cards: which one?

Pick by what the choice changes. The look tells you little, since Wingo UI's Tabs have a segmented variant with the same raised thumb. What differs is the semantics, and with them what a screen reader user expects to happen next.

The choice	Use	What assistive tech gets	Wingo UI
Changes the content already on screen: a time range, a view, units; 2 to 5 short options	Segmented Control	`radiogroup` of `radio`; arrows move and select	Free
Swaps in a different panel of content	Tabs, `variant="segmented"` for this look	`tablist`, `tab`, `tabpanel` linked by `aria-controls`	Free
Changes the URL	Nav Tabs	links in a `nav`, the current one with `aria-current="page"`	Pro
Several options can be on at once (bold and italic, amenities)	Toggle Group `type="multiple"`	buttons with `aria-pressed`	Pro
Each option needs a description or a price	Radio Group `variant="card"`	`radiogroup` of `radio`	Free
More than five options, or long labels	Select	a `combobox` that opens a `listbox` (a bottom sheet on phones)	Free

Apple draws a similar line on iOS: "For switching between completely separate sections of an app, use a tab bar instead." Here are the same segments as Tabs, each with its own panel:

import { Tabs } from "@/components/ui/tabs";
// ProfileForm and BillingForm are your own components

export function AccountTabs() {
  return (
    <Tabs
      variant="segmented"
      fullWidth
      aria-label="Account"
      options={[
        { value: "profile", label: "Profile", content: <ProfileForm /> },
        { value: "billing", label: "Billing", content: <BillingForm /> },
      ]}
    />
  );
}

Live demo: Tabs. The original article embeds an interactive demo here (The same thumb as the segmented control, but each segment opens its own panel: switch from Active to Sold and the list slides in from the side you moved toward). Try it live on wingo-ui.com or open the Tabs docs. Install: npx wingo-ui@latest add tabs

The Toggle Group needs one more note. In single mode Radix also renders it as a radiogroup, but its arrow keys only move focus and Space or Enter presses the item. That is the APG rule for a radio group inside a toolbar, where "the button that is checked does not change" while you arrow through. So an alignment switch in an editor toolbar is a single Toggle Group, and a stand-alone time range is a segmented control. When several can be on, the Toggle Group in multiple mode is the only one of the four that fits:

import { ToggleGroup } from "@/components/ui/toggle-group";

export function AmenityFilter() {
  return (
    <ToggleGroup
      type="multiple"
      variant="outline"
      aria-label="Amenities"
      defaultValue={["parking"]}
      options={[
        { value: "parking", label: "Parking" },
        { value: "pets", label: "Pets allowed" },
        { value: "laundry", label: "In-unit laundry" },
      ]}
    />
  );
}

Live demo: Toggle Group. The original article embeds an interactive demo here (Bold starts on. Press Italic and both stay on, because the formatting group is type multiple; the alignment group next to it is single, so pressing one releases the other). Try it live on wingo-ui.com or open the Toggle Group docs. Install: npx wingo-ui@latest add toggle-group

Radio cards win when the options are not self-explanatory. "Courier, Locker, Pickup" fits in a segmented control; "Home delivery, FedEx, 1-2 days, $9.99" does not, and squeezing it into a segment hides the price that decides the choice. The React form components guide covers the wider choice between a radio group, a select and a combobox in a form.

What goes wrong with segmented controls?

Four things: too many segments, icons mixed with text, a value outside the options, and a missing name.

Too many segments. Apple says "no more than about five segments on iPhone", and Flutter's SegmentedButton docs say they are "typically used in cases where there are only 2-5 options." Six or more labels on a 360px screen get cramped or cut off; switch to a select or scrolling tabs.
Mixing icons and text. Apple's guidelines prefer one or the other in a single control. Pick text, or iconOnly with labels as names.
A controlled value that is not in options. The control shows no thumb, which looks broken. This usually happens when options load after the value.
No name. A radiogroup without aria-label reads as an unnamed group of radios.

What does a complete example look like?

An orders screen that filters one list by status. The choice changes the content on screen and there are four short options, so this is the segmented control's job. Counts ride on badges, and a status line tells screen readers how many orders are visible:

"use client";

import { useState } from "react";
import { SegmentedControl, type SegmentedControlOption } from "@/components/ui/segmented-control";

type Order = { id: string; customer: string; total: number; status: "open" | "shipped" | "returned" };

const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });

export function OrdersPanel({ orders }: { orders: Order[] }) {
  const [status, setStatus] = useState("all");
  const count = (value: Order["status"]) => orders.filter((order) => order.status === value).length;

  const options: SegmentedControlOption[] = [
    { value: "all", label: "All" },
    { value: "open", label: "Open", badge: count("open") },
    { value: "shipped", label: "Shipped" },
    { value: "returned", label: "Returned", badge: count("returned") },
  ];

  const visible = status === "all" ? orders : orders.filter((order) => order.status === status);

  return (
    <section className="flex flex-col gap-4">
      <SegmentedControl
        aria-label="Order status"
        options={options}
        value={status}
        onValueChange={setStatus}
        fullWidth
        className="sm:max-w-md"
      />
      <p role="status" className="text-sm text-muted-foreground">
        {visible.length} {visible.length === 1 ? "order" : "orders"}
      </p>
      <ul className="flex flex-col divide-y divide-border">
        {visible.map((order) => (
          <li key={order.id} className="flex justify-between gap-4 py-3 text-sm">
            <span className="truncate">{order.customer}</span>
            <span className="tabular-nums">{usd.format(order.total)}</span>
          </li>
        ))}
      </ul>
    </section>
  );
}

In a form, drop the state and give it a name. A server action then reads it like any radio:

<form action={saveDelivery}>
  <SegmentedControl
    name="delivery"
    aria-label="Delivery"
    defaultValue="locker"
    fullWidth
    options={[
      { value: "courier", label: "Courier" },
      { value: "locker", label: "Locker" },
      { value: "pickup", label: "Pickup" },
    ]}
  />
  {/* in saveDelivery: formData.get("delivery") */}
</form>

Where should you start?

Install the free control and drop it where a time range, a view switch or a unit toggle lives today:

npx wingo-ui@latest add segmented-control

Tabs and Radio Group are free too. The Toggle Group and Nav Tabs from the table above are part of Wingo UI Pro.

Components in this post

Segmented Control (Free): The iOS segmented control: pick one of a few options on a raised thumb that slides, and on touch drags along with your finger. Install: npx wingo-ui@latest add segmented-control
Tabs (Free): Switch between views of the same page with a sliding indicator: underline for sections, pill for filters, segmented for a compact switch. Install: npx wingo-ui@latest add tabs
Toggle Group (Pro): A row of toggles where one or several stay pressed, for text formatting, alignment, view switches and quick filters. Install: npx wingo-ui@latest add toggle-group
Radio Group (Free): Pick exactly one of a few visible options: rows with a dot that springs in, or cards with icons, prices and a selection ring that slides. Install: npx wingo-ui@latest add radio-group

FAQ

Does shadcn/ui have a segmented control?

Not as of October 2026. Its component list has Tabs, Toggle Group, Radio Group and Button Group, so building one on shadcn/ui means restyling one of those. Pick the base by what the choice does: Tabs for panels, a radio group for a value.

What is the difference between a segmented control and tabs?

Tabs swap in a different panel and expose tablist, tab and tabpanel roles linked by aria-controls. A segmented control picks a value that changes the content already on screen, such as a time range, and is a radiogroup. Apple's guidelines send switching between separate sections of an app to a tab bar.

How many options should a segmented control have?

Two to five. Apple's Human Interface Guidelines say no more than about five segments on iPhone, and Flutter's Material SegmentedButton docs say segmented buttons are typically used with 2 to 5 options. Past five, use a select or a scrolling row of tabs.

Is a segmented control accessible to screen readers?

It is when it is built as a radiogroup of radio items with a name: one tab stop, arrow keys that move and check, and aria-checked on the selected segment. Icon-only segments also need a text name, which Wingo UI's iconOnly mode takes from each option's label.

Can a segmented control submit with a form?

Yes. Give Wingo UI's Segmented Control a name and, inside a form, it submits the selected value like a radio group, so FormData and server actions read it with formData.get.

Is the Wingo UI Segmented Control free?

Yes. The Segmented Control, Tabs, Radio Group and Select are free and install with npx wingo-ui@latest add. The Toggle Group and Nav Tabs are part of Wingo UI Pro.

This article was originally published on the Wingo UI blog: React Segmented Control: iOS Thumb, Drag and When to Use It. The original has the live, interactive demos and is kept up to date.