Contents

Position try

Built-in fallbacks such as flip-block already work inside a class body. When a host design system defines a custom --flip try set, project position-try lets RuleCMS emit @position-try so composer, Preview, and published widgets can register that name — or leave the rules to your site.

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

You wantWithout this catalogWith this catalog
A copied overlay class that says position-try-fallbacks: flip-blockWorks today. The UA already knows flip-block. Leave this page empty.Do not catalog the built-in. Keep it on the class.
A host design system that defines --flip as a custom try setThe class is present. The popover does not flip unless the host already registered @position-try --flip.RuleCMS ships the at-rule with the widget. Preview matches the embed.
A host that already registers the same try setsWorks today. Do not double-define.Turn published inclusion off. Composer and Preview still use the catalog.
The full project catalog is included — not “only fallbacks this widget uses.” Same choice as CSS variables and class definitions.

The project catalog

Open an environment, then Position try. The page is project-scoped: Development, Staging, and Production share it.

  • 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

SurfaceWhat happens
Composer canvas and PreviewAlways injects an unscoped @position-try stylesheet. The published-inclusion flag is ignored here so authors still see the fallback while they work.
Published widget (React SDK and HTML custom element)The widget fetch includes the catalog when inclusion is on. The renderer emits one <style> of @position-try rules. The at-rule is document-global — it is not scoped to the published-key span, and the name is not prefixed.

You do not republish a widget to restyle a try set. The catalog is joined when the host fetches the widget. The next uncached fetch picks up the current declarations.

Published widgets

On the project's Position try page, the Published widgets accordion holds two radios. 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.
Composer and Preview still use the catalog when inclusion is off. Only the published (and Development-draft) embed on your site stops carrying the extra rules.
If you turn inclusion off, the host must define every custom ident the widgets use. A missing @position-try --flip on the live page leaves the overlay where it first landed.

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

  • One catalog per project. Not per environment, not per widget.
  • 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