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

Basic Horizontal Scroll with Cards

The canonical form. Slot any fixed-width children directly into the component; it wraps them in a snap-scrolling viewport with a proportional dot indicator and arrow buttons automatically.

<mds-horizontal-scroll>
  <mds-card class="min-w-[320px]">
    <mds-card-header>Servizio 1</mds-card-header>
    <mds-card-content>Descrizione del primo servizio.</mds-card-content>
  </mds-card>
  <mds-card class="min-w-[320px]">
    <mds-card-header>Servizio 2</mds-card-header>
    <mds-card-content>Descrizione del secondo servizio.</mds-card-content>
  </mds-card>
  <mds-card class="min-w-[320px]">
    <mds-card-header>Servizio 3</mds-card-header>
    <mds-card-content>Descrizione del terzo servizio.</mds-card-content>
  </mds-card>
</mds-horizontal-scroll>

Controlling Navigation Arrow Visibility

Use controls to restrict arrow buttons to specific viewport tiers. The value is the minimum breakpoint at which arrows appear - 'desktop' (default) shows them only on desktop and above; 'all' shows them at every viewport size; 'none' suppresses them entirely.

<!-- Arrows only on desktop and above (default) -->
<mds-horizontal-scroll controls="desktop">
  <!-- slotted items -->
</mds-horizontal-scroll>

<!-- Arrows on all viewports, including mobile -->
<mds-horizontal-scroll controls="all">
  <!-- slotted items -->
</mds-horizontal-scroll>

<!-- No arrows - touch / keyboard scroll only -->
<mds-horizontal-scroll controls="none">
  <!-- slotted items -->
</mds-horizontal-scroll>

Scroll Progress Indicator

Use navigation to choose the scroll-position affordance shown below the items. 'position' (default) renders a proportional translating dot; 'scrollbar' defers to the styled native browser scrollbar; 'none' hides both.

<!-- Dot indicator (default) -->
<mds-horizontal-scroll navigation="position">
  <!-- slotted items -->
</mds-horizontal-scroll>

<!-- Native scrollbar instead of dot -->
<mds-horizontal-scroll navigation="scrollbar">
  <!-- slotted items -->
</mds-horizontal-scroll>

<!-- No progress indicator -->
<mds-horizontal-scroll navigation="none">
  <!-- slotted items -->
</mds-horizontal-scroll>

Snap Alignment

snap controls how each item aligns to the viewport edge when the scroll settles. Use 'start' (default) for left-aligned cards, 'center' for centred carousels, 'end' for right-aligned layouts, or 'none' to allow free scrolling without snapping.

<!-- Leading-edge alignment (default, most common) -->
<mds-horizontal-scroll snap="start">
  <!-- slotted items -->
</mds-horizontal-scroll>

<!-- Centred alignment - good for full-bleed hero carousels -->
<mds-horizontal-scroll snap="center">
  <!-- slotted items -->
</mds-horizontal-scroll>

<!-- Free scroll - no snapping -->
<mds-horizontal-scroll snap="none">
  <!-- slotted items -->
</mds-horizontal-scroll>

Combining Props for a Mobile-Friendly Carousel

Pair controls="all" with snap="center" and navigation="position" to produce a touch-and-arrow carousel that works at every breakpoint.

<mds-horizontal-scroll controls="all" snap="center" navigation="position">
  <mds-card class="min-w-[280px]">
    <mds-card-media>
      <mds-img src="https://example.com/img1.jpg"></mds-img>
    </mds-card-media>
    <mds-card-content>
      <mds-text typography="h5">Categoria A</mds-text>
    </mds-card-content>
  </mds-card>
  <mds-card class="min-w-[280px]">
    <mds-card-media>
      <mds-img src="https://example.com/img2.jpg"></mds-img>
    </mds-card-media>
    <mds-card-content>
      <mds-text typography="h5">Categoria B</mds-text>
    </mds-card-content>
  </mds-card>
</mds-horizontal-scroll>

Styling Customization

Style the component only through its documented --mds-horizontal-scroll-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.sezione-evidenza mds-horizontal-scroll {
  --mds-horizontal-scroll-dot-background: rgb(var(--magma-accent-emphasis));
  --mds-horizontal-scroll-dot-area-background: rgb(var(--magma-accent-surface-hover));
  --mds-horizontal-scroll-max-width: 1200px;
}

Styling the Scrollbar

When navigation="scrollbar" is used, customize the native scrollbar appearance through the dedicated properties. All scrollbar props are browser-dependent and may have no effect on browsers that do not expose a styleable scrollbar.

mds-horizontal-scroll {
  --mds-horizontal-scroll-scrollbar-size: 6px;
  --mds-horizontal-scroll-scrollbar-radius: var(--magma-radius-3xs);
  --mds-horizontal-scroll-scrollbar-thumb-background: rgb(var(--magma-accent-emphasis));
  --mds-horizontal-scroll-scrollbar-track-background: rgb(var(--magma-wash-strong));
}

Customizing the Content Part

The inner scroll container is exposed as ::part(content). Use it sparingly - only when a CSS custom property cannot satisfy your requirement - to apply layout overrides without piercing undocumented internals.

mds-horizontal-scroll::part(content) {
  padding-block: calc(var(--spacing) * 800);
}