Position try

Use built-ins in a class body. Catalog only custom names

Anchor positioning already ships fallback names such as flip-block and flip-inline. Those belong in a Class Definitions body:

position: absolute;
position-try-fallbacks: flip-block;

Do not add flip-block to this catalog. It is a built-in. A class cannot hold a custom try set either: @position-try inside [published-key] .name { … } does not register, and a token cannot hold the block (@ is rejected). This catalog is only for your dashed idents — names like --flip that a class then points at with position-try-fallbacks: --flip.

Authors type --flip and the declarations. RuleCMS emits the unscoped at-rule. You never paste @position-try --flip { … }.

When to use it / when not to

This widget's catalog

Open the widget, then CSS Settings, then Position try. This catalog belongs to this widget.

To change the template for the next widget you create, edit the project catalog.

• Preview dumps the catalog as emitted @position-try blocks — not a :root listing.
• Edit is a dashed ident plus a textarea for the declaration list. Type --flip and position-area: top;, not @position-try --flip { … }. Invalid names and bodies are refused per row. Catalog Save is explicit.

Each entry is one custom try set:

@position-try --flip {
  position-area: top;
  inset: auto;
}

Names must start with --, then a letter or underscore. At most 16 fallbacks; 2000 characters per body. Nested rules, url(, @, and a pasted @position-try wrapper are rejected. Built-in names without -- — flip-block, flip-inline — are refused as catalog names.

What the renderer does with the catalog

Composer and Preview read this widget's draft catalog. The published embed and the Development (dev.) draft GET read the published widget's catalog. Publish is how a draft catalog goes live.

A new widget starts as a copy of the project catalog. After that, edits here do not write back to the project, and later project edits do not come back here.

When the widget catalog is applied, the renderer emits one <style> of unscoped @position-try rules. The at-rule is document-global — it is not scoped to the published-key span, and the name is not prefixed.

Published widgets

On this widget's Position try page, the Published widgets accordion holds two radios. These radios control whether this widget's published and dev. embed carry the definitions. Composer and Preview still use this widget's catalog when inclusion is off. Changing a radio saves immediately. Catalog Save is separate.

• Include these position-try fallbacks when published widgets are rendered. A non-empty catalog is sent with the widget and the renderer defines the try sets. This is the default.
• My apps already register these @position-try rules. Do not include them again when the widget is being rendered. Published widgets still carry class names that point at those fallbacks, but RuleCMS does not ship the @position-try blocks. Your host stylesheet must define them.

How a published widget receives the catalog

Hosts already fetch the widget once. RuleCMS hangs the catalog on that same response as a sibling of the widget, its collections, CSS variables, class definitions, and fonts — not folded into itemList.

{
  "success": true,
  "data": {
    "widget": { "publishedKey": "…", "itemList": "…", "…": "…" },
    "childCollections": { },
    "positionTry": {
      "--flip": "position-area: top;\ninset: auto;"
    }
  }
}

positionTry is omitted when the catalog is empty, when inclusion is off, or if the catalog cannot be read. When inclusion is off, the same response also sends includePositionTry: false so renderers that still receive a map must not emit it. Missing on the payload means include (legacy clients). The widget still loads.

The React renderer (@rulecms/widget-react) and the HTML custom element turn a non-empty catalog into one <style>, for example:

@position-try --flip {
  position-area: top;
  inset: auto;
}

Good to know

• This catalog belongs to this widget. Copy and promote copy these columns as-is. The project catalog is only the starting snapshot.
• Same name, last widget wins. @position-try is document-global. Two embeds that define different declarations for --flip will race. Use the same try set, or turn inclusion off on the host that already owns the name.
• Browser support is CSS anchor positioning. Older browsers ignore the at-rule and keep the first position.
• React and the HTML embed this pass. Other framework SDKs do not emit this catalog yet.
• Leave the catalog empty if the host owns every custom try set, or if you only use built-ins. Class names on elements still work. Nothing extra is sent to the published page.

Related docs

• Class Definitions — put position-try-fallbacks: flip-block or --flip on a class body
• CSS Variables — the token catalog
• Fonts — the typeface catalog; another unscoped at-rule
• Keyframes — named @keyframes; the same name-plus-body pattern
• Themes — host-dark / color-scheme token overrides
• CSS Properties — typed @property
• Cascade layers — wrap class definitions in @layer so they compete with host Tailwind
• Widget chrome — color-scheme and selection on the widget root
• HTML Custom Element Embed
• Development Integration
• API Reference — the public widget GET, including positionTry
• Projects, Environments & Tokens
• The Composer