Skip to content

Overriding & Disabling

When to Use

Use this guide when adjusting a style declared by another module or theme — adding options, hiding it, or replacing it.

Decision

Goal Approach
Hide a style entirely enabled: false in your theme's YAML
Add a few options Re-declare with just the new options (arrays merge)
Wholesale replacement Disable + new plugin ID
Conditional adjustment (per-environment, per-role) hook_ui_styles_styles_alter()

Pattern

Disable an upstream style:

# mytheme.ui_styles.yml
upstream_module_text_color:
  enabled: false

Add options to an upstream style:

upstream_module_text_color:
  options:
    text-brand: "Brand"      # added on top of upstream's options

Programmatic alteration:

function mymodule_ui_styles_styles_alter(array &$definitions): void {
  if (isset($definitions['some_style'])) {
    unset($definitions['some_style']->getOptions()['banned-class']);
  }
}

Common Mistakes

  • Forgetting weight matters when overriding → If multiple sources define the same plugin ID, higher weight wins. Set explicit weights in conflict scenarios
  • Modifying upstream definitions in place → Never edit the upstream module's YAML. Override from your theme or custom module

See Also