Style configuration

What you can change⁠link

Any variant, size, or density you don't set on a component comes from the style configuration. Set that value once for the whole app:

• Outlined fields across a form-heavy app. Set defaultFieldVariant to Outlined.
• A denser data-entry or admin screen. Set defaultFieldDensity, defaultListDensity, defaultMenuDensity, and defaultTableDensity to one of Dense1 to Dense4, where Dense4 is the tightest.
• Filled buttons as the house style. Set defaultButtonVariant to Filled.
• A compact mode the user switches on. Change the density settings while the app runs. Components already on the page update to match.
• Touch targets that take up layout space. Set defaultTouchTarget to Wrapper.

The style configuration chooses a component's variant, size, and density. Colors, corners, and type within that choice come from theming.

Which value a component uses⁠link

• An attribute on the component wins. A component uses its own attribute first, then the style configuration, then Chameleon's default. To give one part of the page a different look, set the attribute on the components in that part.
• An attribute set to a value the setting doesn't list counts as unset, so a field with variant="invalid-value" falls back to the style configuration.
• Reduced motion overrides every animation setting. When the user's system asks for reduced motion, dialogs and popovers open and close without animating, whatever their own attribute or the style configuration says.
• Filled fields hide their label at Dense2 and tighter, because there's no room for it to float into. Pair dense fields with Outlined to keep labels.

Settings⁠link

The table spells names as JavaScript does; in Blazor each starts with a capital letter, such as DefaultButtonVariant. Each value belongs to the enum named in the Values column.

Fields, lists, menus, and tables⁠link

These are the settings you're most likely to change.

Buttons, chips, cards, and sliders⁠link

Touch targets⁠link

The setting decides what happens when a control is smaller than 48 by 48 pixels:

• Overflow extends the area that responds to touch and the mouse beyond the control's visible edge, without changing the layout.
• Wrapper adds space around the control, so it takes up the full 48 by 48 pixels in the layout.
• None limits the area to the visible control. Don't use it unless your layout already guarantees large enough targets.

Rarely changed⁠link

These set motion, loading indicators, scroll indicators, and tooltip placement.

Set your defaults⁠link

Call setStyleConfiguration() once in your app's entry point, naming only the settings you change.

import { ButtonVariant, Density, FieldVariant, setStyleConfiguration } from "@materia-technologies-inc/chameleon-components-web";

setStyleConfiguration({
  defaultButtonVariant: ButtonVariant.Filled,
  defaultFieldVariant: FieldVariant.Outlined,
  defaultFieldDensity: Density.Dense1,
});

Change them while the app runs⁠link

Call setStyleConfiguration() again with the settings to change. Settings you leave out keep their values, and components already on the page update to match.

import { Density, setStyleConfiguration } from "@materia-technologies-inc/chameleon-components-web";

function setCompactMode(compact) {
  setStyleConfiguration({ defaultFieldDensity: compact ? Density.Dense3 : Density.Standard });
}

To return a setting to Chameleon's default, set it to "DEFAULT". getStyleConfiguration() returns the settings as you've set them, with "DEFAULT" for each one you haven't.

Set your defaults⁠link

Call setStyleConfiguration() in your entry point, before the first render, naming only the settings you change.

import { createRoot } from "react-dom/client";
import { ButtonVariant, FieldVariant, setStyleConfiguration } from "@materia-technologies-inc/chameleon-components-react";
import { App } from "./App";

setStyleConfiguration({
  defaultButtonVariant: ButtonVariant.Filled,
  defaultFieldVariant: FieldVariant.Outlined,
});

createRoot(document.getElementById("root")!).render(<App />);

Change them while the app runs⁠link

Call setStyleConfiguration() again, from an event handler for instance, with the settings to change. Settings you leave out keep their values. Components already on the page update to match, with no state or re-render on your side.

To return a setting to Chameleon's default, set it to "DEFAULT". getStyleConfiguration() returns the settings as you've set them, with "DEFAULT" for each one you haven't.

Set your defaults⁠link

Set options.StyleConfiguration where you register Chameleon's services, in Program.cs. Settings you don't name keep Chameleon's defaults.

using Chameleon.Blazor;

builder.Services.AddChameleonServices(options =>
{
    options.StyleConfiguration = new()
    {
        DefaultButtonVariant = ButtonVariant.Filled,
        DefaultFieldVariant = FieldVariant.Outlined,
        DefaultFieldDensity = Density.Dense1,
    };
});

Change them while the app runs⁠link

Inject IChameleonConfigurationService and assign its StyleConfiguration a copy of the current one, made with a with expression. Components already on the page update to match.

@inject IChameleonConfigurationService ChameleonConfiguration

@code {
    private void UseCompactFields()
    {
        ChameleonConfiguration.StyleConfiguration = ChameleonConfiguration.StyleConfiguration with
        {
            DefaultFieldDensity = Density.Dense3,
        };
    }
}

The with expression keeps your other settings. Assigning a new() configuration resets every setting it doesn't name to Chameleon's default.

To return a setting to Chameleon's default, set it to Default.UseDefault.