Troubleshooting

Renderers look unstyled

Symptom: inputs and selects render without their Tailwind styles.

Cause: your shadcn theme tokens aren't set up — the renderers use token utilities (border-input, bg-background, text-muted-foreground, …) that resolve to nothing without them.

Fix: run npx shadcn@latest init (it writes the theme tokens + Tailwind setup), then npx shadcn@latest add @easy-forms/easy-form. Tailwind scans your components/ directory automatically. See Installation.

The form chrome is missing

Symptom: the container, footer, and buttons have no styling.

Cause: the ejected chrome stylesheet (easy-forms.css) isn't loaded, or your theme tokens (--primary, --border, --card, …) aren't defined.

Fix: render with <EasyForm> — it imports components/easy-forms/easy-forms.css for you. (Using <Form> directly? Import that file yourself.) The chrome reads var(--primary) etc., so make sure shadcn init wrote your theme tokens. Don't move the easy-forms* classes into a Tailwind @layer components block.

A group's fields are misaligned

Symptom: in a grid group, the title occupies the first cell and every field shifts.

Cause: the grid class is on the <section> instead of the inner content <div>.

Fix: put the layout/grid class on the inner content <div> in your group renderer.

"Group with dependents is missing an id"

Symptom: a thrown error in development when a group has dependents.

Cause: group-level dependencies need a stable address.

Fix: add an id to the group.

A dependency cycle error

Symptom: DependencyCycleError with a path like a → b → a.

Cause: two fields derive from each other.

Fix: make one field the source of truth and derive the other in a single direction. See Cycle detection.

Edits to the library don't show up

Symptom: in a monorepo, changes to the packages aren't reflected in your app.

Cause: your app imports the built dist, not the source.

Fix: rebuild the packages (or run them in watch mode). For Next.js consuming source, add the packages to transpilePackages.