Variants¶

A variant is a second look for one kind of widget. The theme decides what a button looks like by default. A variant lets you add a compact button, an outlined badge or a card section alongside it. Each widget then picks the look it wants. You would use one when, say, the buttons in a toolbar need to be smaller than the buttons in a form, but you do not want to style each button by hand.

In the designer a variant is shown as a mod. A theme can hold any number of them per component.

Managing variants¶

Say you want a compact button. Open the Theme Designer, go to Components and pick Button. Above the editor, the Mod: bar lists default and every variant. Click Manage Mods and add one named compact. It starts as a copy of the default, with the same parts and states. Select it in the Mod: bar, reduce its padding and font size, and save the theme.

A few points about managing variants:

• Manage Mods adds, renames, copies and deletes variants.
• Names are lowercase words joined by hyphens, for example my-mod.
• Every component except Window can have variants.

Picking a variant on a widget¶

Select the widget on the canvas and open Theme → Variant in its properties panel. Leave it empty to use the default. Charts and parameters have the same Variant field. So does the Show toast action.

Icons are one component that covers every icon in the portal. You choose an icon variant in the icon picker of the widget that shows the icon, next to its manual icon style.

How variants behave¶

A variant is a full, independent copy of the component's values. The rules follow from that:

• Changes to the default do not flow into a variant. When you create a variant it copies default (or the variant you copied). From then on the two are separate.
• Same shape. Every variant has the same parts, states and properties as the component. See Components, parts and states.
• Some variants are built in. The toast ships with success, warning and error, which the Show toast action uses. They appear in the list and can be edited like your own.
• Widget values survive. Values set on the widget itself stay in place when its variant changes, because they are stored separately from the variant.
• Variants cannot carry overrides. Only widgets apply overrides.

Widgets that share a component¶

Variants are defined per component, not per widget. Some widgets use the same component, and some use several components at once. A variant you define is offered to every widget that uses that component.

A widget built from several components still has one Variant field. The name you pick is applied to all of its components. If the variant exists for only some of them, it is still offered, and the other components keep their defaults. So a dense variant defined only on Form Fields and picked on a parameter tightens the field but leaves its label alone.

Good to know¶

• A variant name that no longer exists in the theme renders as default, without a warning.