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

Full Preferences Panel

The canonical form: slot every mds-pref-* control directly inside <mds-pref>. The parent coordinates the theme and mode controls automatically (a scheme-constrained theme locks the matching mode item) - no extra wiring is needed.

<mds-pref>
  <mds-pref-mode></mds-pref-mode>
  <mds-pref-theme>
    <mds-pref-theme-item name="default"></mds-pref-theme-item>
    <mds-pref-theme-item name="cool"></mds-pref-theme-item>
  </mds-pref-theme>
  <mds-pref-contrast></mds-pref-contrast>
  <mds-pref-animation></mds-pref-animation>
  <mds-pref-consumption></mds-pref-consumption>
  <mds-pref-language>
    <mds-pref-language-item code="it"></mds-pref-language-item>
    <mds-pref-language-item code="en"></mds-pref-language-item>
  </mds-pref-language>
</mds-pref>

Partial Panel - Subset of Controls

Slot only the controls your application needs. <mds-pref> renders whatever children are present; omitted controls are simply absent.

<!-- Accessibility-only panel: contrast and animation controls -->
<mds-pref>
  <mds-pref-contrast></mds-pref-contrast>
  <mds-pref-animation></mds-pref-animation>
</mds-pref>

Controlling Size

A later change of the parent’s size drives all child controls at once, but the initial value is not forwarded (the watcher does not run on load): for the first render set size on each child as well.

<!-- Compact panel for a sidebar or popover -->
<mds-pref size="sm">
  <mds-pref-mode size="sm"></mds-pref-mode>
  <mds-pref-contrast size="sm"></mds-pref-contrast>
  <mds-pref-animation size="sm"></mds-pref-animation>
</mds-pref>

Headless Controller Mode

Set the controller boolean attribute when you need the preference engine to apply saved preferences from localStorage on page load without rendering any visible UI. The host is hidden via CSS (display: none) and still activates all child preference controls.

<!-- Place in <body>; the panel is invisible but activates stored preferences -->
<mds-pref controller>
  <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-language>
    <mds-pref-language-item code="it"></mds-pref-language-item>
    <mds-pref-language-item code="en"></mds-pref-language-item>
  </mds-pref-language>
</mds-pref>

Language Selector with Multiple Languages

<mds-pref-language> requires its child <mds-pref-language-item> elements to be present; the items are not self-generating. Pass language codes supported by your application.

<mds-pref>
  <mds-pref-language>
    <mds-pref-language-item code="it"></mds-pref-language-item>
    <mds-pref-language-item code="en"></mds-pref-language-item>
    <mds-pref-language-item code="el"></mds-pref-language-item>
    <mds-pref-language-item code="es"></mds-pref-language-item>
  </mds-pref-language>
</mds-pref>

Reload Notice Handling

<mds-pref> has an inline caption telling the user to refresh the page after a consumption or language change, but today it never shows in a visible panel: the parent listens for the children’s mdsPrefChange only in controller mode, where the host is hidden. If your application needs the hint, provide it yourself, and keep in mind that the children emit mdsPrefChange on page load too, not only on a user’s choice.