Display Controls

Display controls are used to present information to users without requiring input.

TextBlock

A lightweight control for displaying read-only text.

Properties

Text: The text content (string)
FontSize: Size of the font (double)
FontWeight: Weight of the font - Normal, Bold, Light, etc.
FontFamily: Font family name (string)
FontStyle: Style of the font - Normal, Italic, Oblique
Foreground: Text color (IBrush)
Background: Background color (IBrush)
TextAlignment: Alignment - Left, Center, Right, Justify
TextWrapping: Wrapping mode - NoWrap, Wrap, WrapWithOverflow
TextTrimming: Trimming mode - None, CharacterEllipsis, WordEllipsis
TextDecorations: Underline, strikethrough, etc.
LineHeight: Height of each line (double)
MaxLines: Maximum number of lines to display (int)

Example

XAML
C#

<!-- Simple text -->
<TextBlock Text="Hello, Avalonia!" />

<!-- Styled text -->
<TextBlock 
  Text="Welcome to Avalonia UI"
  FontSize="24"
  FontWeight="Bold"
  Foreground="#007ACC" />

<!-- Text with wrapping -->
<TextBlock 
  Text="This is a long text that will wrap to multiple lines when the window is resized."
  TextWrapping="Wrap"
  MaxWidth="300" />

<!-- Text with trimming -->
<TextBlock 
  Text="This text is too long and will be trimmed with ellipsis"
  TextTrimming="CharacterEllipsis"
  MaxWidth="200" />

<!-- Formatted text with inlines -->
<TextBlock>
  <Run Text="This is " />
  <Run Text="bold text" FontWeight="Bold" />
  <Run Text=" and this is " />
  <Run Text="italic text" FontStyle="Italic" />
</TextBlock>

<!-- Text with underline -->
<TextBlock Text="Underlined text" TextDecorations="Underline" />

// Simple text
var textBlock = new TextBlock
{
    Text = "Hello, Avalonia!"
};

// Styled text
var styledText = new TextBlock
{
    Text = "Welcome to Avalonia UI",
    FontSize = 24,
    FontWeight = FontWeight.Bold,
    Foreground = Brushes.Blue
};

// Text with wrapping
var wrappingText = new TextBlock
{
    Text = "Long text...",
    TextWrapping = TextWrapping.Wrap,
    MaxWidth = 300
};

Text Formatting

Use Run elements for inline formatting:

<TextBlock>
  <Run Text="Normal" />
  <Run Text="Bold" FontWeight="Bold" />
  <Run Text="Colored" Foreground="Red" />
  <LineBreak />
  <Run Text="Second line" />
</TextBlock>

Image

Displays image content from various sources.

Properties

Source: Image source (IImage)
Stretch: How image is sized - None, Fill, Uniform, UniformToFill
StretchDirection: Scaling direction - Both, UpOnly, DownOnly

Example

XAML
C#

<!-- Image from file -->
<Image Source="/Assets/logo.png" Width="200" Height="200" />

<!-- Image with stretch modes -->
<Image Source="/Assets/photo.jpg" Stretch="Uniform" />

<!-- Image from URL -->
<Image Source="https://example.com/image.png" />

<!-- Image from binding -->
<Image Source="{Binding ProfilePicture}" Width="100" Height="100" />

<!-- Image with different stretch modes -->
<Grid ColumnDefinitions="*,*,*,*">
  <Image Grid.Column="0" Source="/Assets/logo.png" Stretch="None" />
  <Image Grid.Column="1" Source="/Assets/logo.png" Stretch="Fill" />
  <Image Grid.Column="2" Source="/Assets/logo.png" Stretch="Uniform" />
  <Image Grid.Column="3" Source="/Assets/logo.png" Stretch="UniformToFill" />
</Grid>

// Image from file
var image = new Image
{
    Source = new Bitmap("Assets/logo.png"),
    Width = 200,
    Height = 200
};

// Image from stream
using (var stream = File.OpenRead("image.png"))
{
    var image = new Image
    {
        Source = new Bitmap(stream)
    };
}

// Image from URL
var image = new Image
{
    Source = new Bitmap("https://example.com/image.png")
};

Stretch Modes

None: Display at original size
Fill: Stretch to fill (may distort)
Uniform: Scale to fit (maintains aspect ratio)
UniformToFill: Scale to fill (maintains aspect ratio, may crop)

Border

A control that decorates a child with a border and background.

Properties

Background: Background brush (IBrush)
BackgroundSizing: How background is drawn - InnerBorderEdge, CenterBorder, OuterBorderEdge
BorderBrush: Border color (IBrush)
BorderThickness: Border width (Thickness)
CornerRadius: Radius for rounded corners (CornerRadius)
BoxShadow: Shadow effects (BoxShadows)
Padding: Inner padding (Thickness)
Child: Single child element

Example

XAML
C#

<!-- Simple border -->
<Border BorderBrush="#007ACC" BorderThickness="2">
  <TextBlock Text="Content with border" />
</Border>

<!-- Border with background -->
<Border 
  Background="#F0F0F0"
  BorderBrush="#CCCCCC"
  BorderThickness="1"
  Padding="10">
  <TextBlock Text="Content with background" />
</Border>

<!-- Rounded border -->
<Border 
  Background="White"
  BorderBrush="#007ACC"
  BorderThickness="2"
  CornerRadius="8"
  Padding="15">
  <TextBlock Text="Rounded corners" />
</Border>

<!-- Border with shadow -->
<Border 
  Background="White"
  CornerRadius="4"
  BoxShadow="0 4 8 0 #40000000"
  Padding="20">
  <TextBlock Text="Card with shadow" />
</Border>

<!-- Border with different thickness on each side -->
<Border BorderBrush="Black" BorderThickness="1,2,3,4">
  <TextBlock Text="Different border thickness" />
</Border>

// Simple border
var border = new Border
{
    BorderBrush = Brushes.Blue,
    BorderThickness = new Thickness(2),
    Child = new TextBlock { Text = "Content" }
};

// Border with rounded corners
var roundedBorder = new Border
{
    Background = Brushes.White,
    BorderBrush = Brushes.Gray,
    BorderThickness = new Thickness(1),
    CornerRadius = new CornerRadius(8),
    Padding = new Thickness(15),
    Child = new TextBlock { Text = "Rounded" }
};

// Border with shadow
var shadowBorder = new Border
{
    Background = Brushes.White,
    CornerRadius = new CornerRadius(4),
    BoxShadow = BoxShadows.Parse("0 4 8 0 #40000000")
};

ProgressBar

Shows progress of an operation.

<!-- Determinate progress -->
<ProgressBar 
  Minimum="0" 
  Maximum="100" 
  Value="{Binding DownloadProgress}" />

<!-- Indeterminate progress -->
<ProgressBar IsIndeterminate="True" />

Label

A control that displays text and can specify a target for keyboard focus.

<StackPanel>
  <Label Content="Name:" Target="nameTextBox" />
  <TextBox Name="nameTextBox" />
</StackPanel>

Separator

A line that separates items.

<StackPanel>
  <TextBlock Text="Section 1" />
  <Separator />
  <TextBlock Text="Section 2" />
</StackPanel>

Viewbox

A container that scales its child to fill available space.

<Viewbox Stretch="Uniform">
  <Canvas Width="100" Height="100">
    <Ellipse Width="100" Height="100" Fill="Blue" />
  </Canvas>
</Viewbox>

ContentControl

Base class for controls that display a single piece of content.

<ContentControl Content="{Binding CurrentView}">
  <ContentControl.ContentTemplate>
    <DataTemplate>
      <TextBlock Text="{Binding Title}" />
    </DataTemplate>
  </ContentControl.ContentTemplate>
</ContentControl>

Best Practices

Use TextBlock for read-only text - It’s more lightweight than TextBox
Optimize images - Use appropriate resolutions and formats
Use vector graphics when possible - SVG/PathIcon scales better than bitmaps
Apply borders judiciously - Too many borders can clutter the UI
Consider accessibility - Ensure sufficient contrast for text

Styling Display Controls

<Window.Styles>
  <Style Selector="TextBlock.header">
    <Setter Property="FontSize" Value="24" />
    <Setter Property="FontWeight" Value="Bold" />
    <Setter Property="Margin" Value="0,0,0,10" />
  </Style>
  
  <Style Selector="Border.card">
    <Setter Property="Background" Value="White" />
    <Setter Property="CornerRadius" Value="8" />
    <Setter Property="BoxShadow" Value="0 2 4 0 #20000000" />
    <Setter Property="Padding" Value="16" />
  </Style>
</Window.Styles>

Performance Tips

TextBlock is more efficient than Label for simple text display
Cache images when displaying the same image multiple times
Use async loading for images from URLs
Virtualize long lists of display controls

Get Started

Core Concepts

Controls

Platform Support

Advanced Topics

Guides

TextBlock

Properties

Example

Text Formatting

Image

Properties

Example

Stretch Modes

Border

Properties

Example

ProgressBar

Label

Separator

Viewbox

ContentControl

Best Practices

Styling Display Controls

Performance Tips

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

Controls

Platform Support

Advanced Topics

Guides

​TextBlock

​Properties

​Example

​Text Formatting

​Image

​Properties

​Example

​Stretch Modes

​Border

​Properties

​Example

​ProgressBar

​Label

​Separator

​Viewbox

​ContentControl

​Best Practices

​Styling Display Controls

​Performance Tips

​See Also

Build docs developers (and LLMs) love

TextBlock

Properties

Example

Text Formatting

Image

Properties

Example

Stretch Modes

Border

Properties

Example

ProgressBar

Label

Separator

Viewbox

ContentControl

Best Practices

Styling Display Controls

Performance Tips

See Also