Skip to main content

Fluid Primitives provides headless, accessible primitives built on Zag.js state machines. They handle behavior and accessibility, you handle styling.

A primitive is an unstyled component part with built-in:

Primitives use the primitives namespace:

Primitives (primitives:*) are the unstyled building blocks. Every part is its own tag, which gives you full control over the markup.

Components (ui:*) are your wrappers around primitives. They add your styling and can simplify the API, for example by combining parts.

A tooltip made of primitives:

Your component can combine parts and provide an abstraction level that matches your design system:

Of course its possible to use every other namespace for your own components as well.

Wrap each primitive part in a template of your own. A tooltip needs three:

ui/Tooltip/Root.html:

ui/Tooltip/Trigger.html:

ui/Tooltip/Content.html:

Use your styled, simplified API in a template:

Imports prop definitions from another component, so your wrapper accepts the same props as the primitive without redeclaring them.

Set as="rootProps" when the wrapper renders the primitive (the common case above). It binds the imported, forwardable prop names to {rootProps} for spreadProps. Omit as to reuse just the prop definitions, see Inheriting Props.

Forwards the props bound by the as of ui:useProps to the primitive in one call.

A primitive hydrates in the browser through an entry file. Load it in the root template, so a page includes it when it uses the component:

Use the TYPO3 CLI to scaffold components:

This generates component files with basic Tailwind styling as a starting point.

The root template of every added component ends with a <vite:asset> line that loads its .entry.ts file, so the component hydrates without extra setup:

ui:add fills in the path the component is written to, following --extension and --path. The tag needs praetorius/vite-asset-collector with the vite Fluid namespace registered, and a Vite config that picks up Resources/Private/Components/**/*.entry.ts as entrypoints. ui:add warns when the namespace is missing. If you load scripts differently, replace the line with your own, see JavaScript Entry Files. Repeating the tag is fine, the asset is included once per page.

Browse every primitive with examples and API documentation in Components.

The CLI scaffolding is a starting point for your own design system. Expect to:

ui:add leaves components you already have untouched. If any file of the components you add exists in the target folder, nothing is written and the command fails with the list of files in the way. Add --force to overwrite the whole components with the registry version, or move your customized component aside first. Other files in the folders stay as they are.

Once the code is in your project, it is yours: copy it, shape it, rename parts.