Correct and idiomatic ways to use the <mds-pref-contrast> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Inside the Full Preferences Panel

The canonical form. Slot <mds-pref-contrast> directly inside <mds-pref> alongside the other preference controls. The parent panel forwards later changes of its size to every child.

<mds-pref>
  <mds-pref-mode></mds-pref-mode>
  <mds-pref-contrast></mds-pref-contrast>
  <mds-pref-animation></mds-pref-animation>
  <mds-pref-consumption></mds-pref-consumption>
</mds-pref>

Accessibility-Only Panel

When an application exposes only accessibility controls, slot <mds-pref-contrast> together with <mds-pref-animation> inside a minimal <mds-pref>. Omitted preference controls are simply absent - no extra configuration is required.

<mds-pref>
  <mds-pref-contrast></mds-pref-contrast>
  <mds-pref-animation></mds-pref-animation>
</mds-pref>

Forcing a Contrast Level Programmatically

Set the mode prop explicitly when the host application needs to impose a contrast level regardless of the user’s last persisted choice. Valid values are more (high contrast), system (defers to OS prefers-contrast), and no-preference (design-system default).

<!-- Force high contrast: the class goes on <html>, so it applies to the whole document -->
<mds-pref-contrast mode="more"></mds-pref-contrast>

Reacting to Contrast Changes

Listen for mdsPrefChange to act whenever the user switches the contrast mode. The event detail carries { preference: 'contrast' } so a single handler can distinguish between the different preference controls; the event also fires on page load, so do not read each one as a user’s choice.

<mds-pref-contrast id="contrast-ctrl"></mds-pref-contrast>

<script>
  document
    .getElementById('contrast-ctrl')
    .addEventListener('mdsPrefChange', (event) => {
      if (event.detail.preference === 'contrast') {
        console.log('Preferenza contrasto aggiornata');
      }
    });
</script>

Controlling Size

Use the size prop when rendering <mds-pref-contrast> outside <mds-pref> and a specific tab-item size is required. Inside <mds-pref>, the parent forwards later changes of its own size, not the initial value, so set it on this child as well.

<!-- Compact size for a toolbar or narrow panel -->
<mds-pref-contrast size="sm"></mds-pref-contrast>

<!-- Default (medium) size - equivalent to omitting the prop -->
<mds-pref-contrast size="md"></mds-pref-contrast>

Restoring the Last Persisted Choice on Page Load

Leave mode unset. On load the component reads localStorage for the key mdsPrefContrast set during a previous session, falls back to system when nothing is stored, and applies the resolved class to <html> immediately - no application bootstrap code is needed.

<!-- mode is intentionally absent: the component self-restores -->
<mds-pref-contrast></mds-pref-contrast>