Frequently Asked Questions
Why the need for normalizeProps
?
The goal of normalizeProps
is to convert the props of the component into the
format that is compatible with the respective framework.
It is also used to ensure that the returned properties are strongly typed.
There are subtle difference between how element attributes are named across frameworks like React, Solid and Vue. Here are some examples:
Keydown listener
- React and Solid: The keydown listener property is
onKeyDown
. - Vue: The keydown listener property is
onKeydown
.
Styles
- React: Pass a numeric value for margin attributes like
{ marginBottom: 4 }
. - Solid: It has to be
{ "margin-bottom": "4px" }
. - Vue: You need to ensure the value is a string with unit.
{ marginBottom: "4px" }
.
These little nuances between frameworks are handled automatically when you use
normalizeProps
.
How can I attach custom extra event handlers to the elements?
See the approach here.
How can I get Zag working in a custom window environment?
See the approach here.
What would it take to support other frameworks?
We're currently interested in supporting as many frameworks as possible. The key requirements are:
-
Support for "spread props": The framework should have support for spreading attributes and event handlers.
-
Exposed Typings: The framework should expose the typings for the attributes and event handlers. This is optional but would provide the best DX.
How do I upgrade all zag dependencies?
Since we use independent versioning for each zag package, it can sometimes be inconvenient to upgrade all dependencies individually.
You can use scoped upgrades feature in your package manager to update all zag packages seamlessly.
pnpm up "@zag-js/*" # or yarn upgrade --scope @zag-js # or npm up @zag-js/...
Why am I getting proxyState is not iterable
error?
This happens when there's a mismatch in the versions of @zag-js/*
modules or
multiple instances of @zag-js/store
are installed. It is common with PNPM
monorepo users.
To fix this, you can use the overrides
feature in your package.json
to
ensure that all @zag-js/*
modules are on the same version.
{ "pnpm": { "overrides": { "@zag-js/store": "^0.12.0" } } }
Edit this page on GitHub