ScrollBar

Quick start

Use ScrollBar when you want to expose scroll state, viewport position, or range navigation on a custom surface. For standard content scrolling, use ScrollViewer, which creates and synchronizes its own internal scroll bars automatically.

Minimal horizontal bar

<ScrollBar Width="280"
           Orientation="Horizontal"
           Minimum="0"
           Maximum="100"
           ViewportSize="20"
           Value="35" />

Vertical bar for a tall surface

<ScrollBar Height="220"
           Orientation="Vertical"
           Minimum="0"
           Maximum="1200"
           ViewportSize="240"
           Value="360" />

Styled bar using control colors

<ScrollBar Width="300"
           Orientation="Horizontal"
           Minimum="0"
           Maximum="800"
           ViewportSize="160"
           Value="240"
           Background="#152231"
           Foreground="#6FB7FF"
           BorderBrush="#27425A"
           BorderThickness="1" />

What the range means

ScrollBar models a visible window inside a larger logical extent. The key point is that Maximum represents the end of the total extent, not the last legal scroll offset.

<ScrollBar Width="320"
           Orientation="Horizontal"
           Minimum="0"
           Maximum="1000"
           ViewportSize="320"
           Value="180" />

In that example, the represented extent is 1000 units, the visible window is 320 units, and the largest practical offset is 680, not 1000.

Thumb sizing and movement

The thumb is laid out inside the Track area between the two line buttons. Its size and position are driven by the extent, viewport, and current value.

• If ViewportSize is 0, the thumb falls back to roughly 10% of the track, still respecting the 14-unit minimum.
• The thumb position is normalized across the scrollable range, not the full extent.
• The line buttons are arranged first, then the remaining track space is used for the thumb and page regions.

<StackPanel>
  <ScrollBar Width="260"
             Orientation="Horizontal"
             Minimum="0"
             Maximum="100"
             ViewportSize="80"
             Value="10" />

  <ScrollBar Width="260"
             Orientation="Horizontal"
             Minimum="0"
             Maximum="100"
             ViewportSize="10"
             Value="10"
             Margin="0,8,0,0" />
</StackPanel>

The first bar shows a large thumb because the viewport covers most of the extent. The second shows a much smaller thumb because the viewport is only a small slice of the same range.

Template structure

ScrollBar is a templated control, not a content host. The default template uses named parts, and custom templates must preserve those parts for the control to function.

• The default template root is a Track.
• The line buttons are RepeatButton instances, so holding the pointer continues line stepping.
• The thumb is a Thumb, which supplies drag events and pointer capture for thumb movement.

Template example

<ControlTemplate TargetType="ScrollBar">
  <Track x:Name="PART_Track">
    <RepeatButton x:Name="PART_LineUpButton" />
    <Thumb x:Name="PART_Thumb" />
    <RepeatButton x:Name="PART_LineDownButton" />
  </Track>
</ControlTemplate>

Interaction model

The control owns its own pointer behavior. The same interaction rules apply whether the bar is used on its own or inside a ScrollViewer.

• The decrease and increase buttons move the value by SmallChange.
• Track clicks use LargeChange.
• Drag math and track clicks clamp the resulting value to the legal scrollable range.
• ValueChanged is raised whenever the effective value changes.

Interaction example

var bar = new ScrollBar
{
    Orientation = Orientation.Vertical,
    Height = 240f,
    Minimum = 0f,
    Maximum = 1200f,
    ViewportSize = 240f,
    SmallChange = 24f,
    LargeChange = 240f
};

bar.ValueChanged += (_, _) =>
{
    cameraY = bar.Value;
};

Layout and sizing

ScrollBar is not a content host. Its size comes from normal layout and from whatever template you apply, so standalone bars are easiest to control when you set an explicit Width or Height.

• Use normal layout properties like Width and Height to size the control.
• The default template uses square-ish line buttons sized from the available bar thickness.
• Custom templates can replace the visual structure, as long as the required parts remain present and wired inside PART_Track.

<Grid>
  <Grid.ColumnDefinitions>
    <ColumnDefinition Width="*" />
    <ColumnDefinition Width="Auto" />
  </Grid.ColumnDefinitions>

  <Canvas Grid.Column="0" Width="420" Height="220" />

  <ScrollBar Grid.Column="1"
             Width="16"
             Height="220"
             Orientation="Vertical"
             Minimum="0"
             Maximum="600"
             ViewportSize="220"
             Value="120" />
</Grid>

Appearance and styling

The default template is visually conservative and intended to be restyled. The normal control styling surface drives the default visuals.

• The default line buttons use the bar's Foreground for their arrow glyphs.
• Template-driven styling works for standalone bars and for bars hosted inside ScrollViewer.
• The default template binds the track border and thumb outline to the control's border styling surface.

<StackPanel>
  <ScrollBar Width="280"
             Orientation="Horizontal"
             Minimum="0"
             Maximum="300"
             ViewportSize="80"
             Value="60"
             Background="#132131"
             Foreground="#77D1FF"
             BorderBrush="#365B7D"
             BorderThickness="1" />

  <ScrollBar Width="280"
             Orientation="Horizontal"
             Minimum="0"
             Maximum="300"
             ViewportSize="80"
             Value="60"
             Background="#1B2D41"
             Foreground="#FFB347"
             BorderBrush="#6D5334"
             BorderThickness="1"
             Margin="0,8,0,0" />
</StackPanel>

The first bar keeps a cool track and thumb palette. The second uses a warmer track/thumb combination without needing any dedicated scrollbar-only color properties.

ScrollViewer ownership

ScrollViewer creates and owns its internal horizontal and vertical ScrollBar instances. Those bars are regular ScrollBar controls whose range values are synchronized by the viewer.

<ScrollViewer Width="360"
              Height="220"
              HorizontalScrollBarVisibility="Auto"
              VerticalScrollBarVisibility="Auto"
              ScrollBarThickness="16">
  <Canvas Width="960" Height="640">
    <Border Canvas.Left="40"
            Canvas.Top="32"
            Width="200"
            Height="120"
            Background="#183149"
            BorderBrush="#5A9CD4"
            BorderThickness="1" />
  </Canvas>
</ScrollViewer>

If your goal is end-user scrolling of a content surface, this is the usual pattern. The viewer owns the offsets, extents, and viewport metrics, while the internal bars surface those values through the normal scrollbar UI.

Property and event reference

Patterns and examples

Viewport indicator for a large canvas

<Grid>
  <Grid.ColumnDefinitions>
    <ColumnDefinition Width="*" />
    <ColumnDefinition Width="Auto" />
  </Grid.ColumnDefinitions>

  <Canvas x:Name="WorldCanvas" Grid.Column="0" Width="1200" Height="900" />

  <ScrollBar Grid.Column="1"
             Height="260"
             Orientation="Vertical"
             Minimum="0"
             Maximum="900"
             ViewportSize="260"
             Value="{Binding CameraY}"
             Background="#13202E"
             Foreground="#5FA8E8"
             BorderBrush="#27445A"
             BorderThickness="1" />
</Grid>

Horizontal timeline navigator

<ScrollBar Width="420"
           Orientation="Horizontal"
           Minimum="0"
           Maximum="{Binding TimelineLength}"
           ViewportSize="{Binding VisibleRange}"
           Value="{Binding TimelineOffset}"
           Background="#0F1823"
           Foreground="#F5B04C" />

Programmatic setup in code

var bar = new ScrollBar
{
    Orientation = Orientation.Vertical,
    Width = 16f,
    Height = 240f,
    Minimum = 0f,
    Maximum = documentHeight,
    ViewportSize = viewportHeight,
    Value = currentOffset,
    Background = new Color(19, 32, 46),
    Foreground = new Color(95, 168, 232),
    BorderBrush = new Color(39, 68, 90),
    BorderThickness = new Thickness(1f)
};

bar.Value = nextOffset;
bar.ValueChanged += (_, _) => camera.Y = bar.Value;

Custom template styling

<Style TargetType="ScrollBar">
  <Setter Property="Background" Value="#102030" />
  <Setter Property="Foreground" Value="#76C7FF" />
  <Setter Property="BorderBrush" Value="#28455C" />
  <Setter Property="BorderThickness" Value="1" />
</Style>

Prefer ScrollViewer for interactive content scrolling

<ScrollViewer Width="340"
              Height="220"
              VerticalScrollBarVisibility="Auto">
  <StackPanel>
    <TextBlock Text="Entry 1" />
    <TextBlock Text="Entry 2" />
    <TextBlock Text="Entry 3" />
    <TextBlock Text="Entry 4" />
    <TextBlock Text="Entry 5" />
    <TextBlock Text="Entry 6" />
    <TextBlock Text="Entry 7" />
  </StackPanel>
</ScrollViewer>

Notes and pitfalls