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

Default Usage Inside mds-pref

The standard form. Place <mds-pref-animation> as a direct slot child of <mds-pref>. No mode or size is required - the component restores the last persisted choice and defaults to system on a first visit.

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

Combined Preferences Panel

Place multiple mds-pref-* children inside the same <mds-pref>. The parent forwards later changes of its size to every child.

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

Pre-selecting a Mode via mode

Pass mode to override the persisted value and start from a known state - for example, a first-run onboarding screen that starts with reduced motion.

<mds-pref>
  <mds-pref-animation mode="reduce"></mds-pref-animation>
</mds-pref>

Listening for Changes

Handle mdsPrefChange when the host application needs to react - for example, to announce the new setting or trigger a soft refresh. The event also fires on page load, so do not read each one as a user’s choice.

<mds-pref id="prefs">
  <mds-pref-animation></mds-pref-animation>
</mds-pref>

<script>
  document.getElementById('prefs').addEventListener('mdsPrefChange', (event) => {
    // event.detail.preference === 'animation'
    console.log('Preferenza animazioni aggiornata', event.detail);
  });
</script>

Compact Size

Set size="sm" on the parent <mds-pref> and on each mds-pref-* child to shrink the tab items consistently: the parent forwards later changes of its size, not the initial value.

<!-- In the panel: on the parent and on each child -->
<mds-pref size="sm">
  <mds-pref-animation size="sm"></mds-pref-animation>
  <mds-pref-contrast size="sm"></mds-pref-contrast>
</mds-pref>

<!-- Acceptable when used standalone -->
<mds-pref-animation size="sm"></mds-pref-animation>

Silent Controller (Hidden Preference Sync)

When a <mds-pref controller> element is placed in the DOM, it applies preferences silently without rendering any UI. <mds-pref-animation> inside it restores the persisted animation class on <html> on load without showing the tab group.

<!-- Place once, near the root - no UI is rendered -->
<mds-pref controller>
  <mds-pref-animation></mds-pref-animation>
</mds-pref>