ProGuide Style Guide

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization:  Esri, http://www.esri.com
Date:          10/02/2023
ArcGIS Pro:    3.2
Visual Studio: 2022

This guide is a reference for styling UI Components in your add-in and configuration. ArcGIS Pro provides developers with various XAML Styles to use for styling WPF UI components. ArcGIS Pro Framework will use the correct styling for the Dark and Light themes when the built-in Pro Styles are used. Refer to the UI Controls listed below for their available ESRI styles.

Certain UI elements such as TextBlocks, radio buttons, etc do not need any styling. ArcGIS Pro will automatically style them using the "Default" style. Certain UI elements such as Buttons, ListBoxes will have to be styled so that they work well within ArcGIS Pro.

Contents

• User Control
• Windows
• Brushes
• Button
• Toggle button
• Check boxes
• Colors
• Combo boxes
• DataGrid
• Expanders
• Galleries
• Hyperlinks
• Image
• Label
• List Box
• List View
• Message boxes
• Radio Buttons
• Textblocks
• Textbox

---

ArcGIS Pro XAML styles should be used as DynamicResources while styling the UI elements in an add-in. Add this code snippet to your xaml so that these Dynamic resources will load in Design mode in Visual Studio.

<UserControl ...
      xmlns:extensions="clr-namespace:ArcGIS.Desktop.Extensions;assembly=ArcGIS.Desktop.Extensions"
      ...>
<UserControl.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
     <extensions:DesignOnlyResourceDictionary Source="pack://application:,,,/ArcGIS.Desktop.Framework;component\Themes\Default.xaml"/>
            </ResourceDictionary.MergedDictionaries>
      </ResourceDictionary>
 </UserControl.Resources>

User Control

Default Style: Yes

Avoid setting a background brush for a User Control. User controls will automatically inherit the correct background brush for Light and Dark themes. If you do have to set the background, use one of these Esri brushes.

To style UI elements within the user control, refer to the TextBlocks, Brushes, buttons, etc., sections in this wiki.

Windows

Default Style: Yes

Custom windows within add-ins should derive from ArcGIS.Desktop.Framework.Controls.ProWindow to inherit a correctly styled Title Bar and background (by default, in Visual Studio a custom window will be derived from System.Windows.Window). If you do have to set the window background, use one of these Esri brushes.

Note that in the example code below the System.Windows.Window has been changed to a ArcGIS.Desktop.Framework.Controls.ProWindow:

<controls:ProWindow x:Class="Geocode.GeocodeWindow"
     …
     xmlns:controls="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
     …
     Height="150" Width="420" Title="Geocode">

public partial class GeocodeWindow : ProWindow
    {

Brushes

In most cases ArcGIS Pro will set the correct default foreground and background brushes. However, if you do need to explicitly set the foreground or background colors you must use an Esri brush . "Esri" brushes will resolve to the correct Light or Dark color variant depending on the corresponding theme of Pro.

For example, Esri_TextMenuBrush uses the color white(#FFFFFF) for Light theme and dark gray (#D1D1D1) (the reverse) for Dark theme. This is true of all the other brushes. Each brush has a light and dark equivalent.

Available Esri Brushes

Button

Default Style: No
Available Styles:

Style name	Button
Esri_Button	Simple button with border
Esri_ButtonBorderless	Simple borderless button
Esri_ButtonClose	Close button
Esri_ButtonBack	Back button
Esri_ButtonBackSmall	Small back button
Esri_ButtonForwardSmall	Small forward button
Esri_ButtonUpSmall	Small up button
Esri_ButtonDownSmall	Small down button
Esri_ButtonUpSmallBorderless	Borderless up button
Esri_ButtonForwardSmallBorderless	Borderless forward button

Buttons have no default style. You have to apply one of the available Esri styles listed above to a button element.

Do not specify button attributes such as Foreground, Background, unless you want to override the Esri styles.

Buttons

• Button with border

 <Button Style="{DynamicResource Esri_Button}">
   Button
 </Button>

Arrow Buttons

• Large Arrow Button

 <Button Style="{DynamicResource Esri_ButtonBack}">
 </Button>

• Small Arrow Buttons

 <Button Style="{DynamicResource Esri_ButtonBackSmall}">
 </Button>

 <Button Style="{DynamicResource Esri_ButtonForwardSmall}">
 </Button>

 <Button Style="{DynamicResource Esri_ButtonUpSmall}">
 </Button>

 <Button Style="{DynamicResource Esri_ButtonDownSmall}">
 </Button>

• Borderless Arrows

 <Button Style="{DynamicResource Esri_ButtonUpSmallBorderless}">
 </Button>

 <Button Style="{DynamicResource Esri_ButtonForwardSmallBorderless}">
 </Button>

Toggle button

Default Style: No
Available Styles:

Style name	Toggle Button
Esri_ButtonToggle	Simple toggle button
Esri_ToggleButtonTrayButton	Map and Layout tray toggle button

Toggle buttons have no default style. You have to apply one of the available Esri styles listed above to a toggle buton element.

Do not specify attributes such as Foreground, Background, unless you want to override the Esri styles.

• Simple toggle button

 <Button Style="{DynamicResource Esri_ButtonToggle}">
   Button
 </Button>

• Map and Layout tray toggle button

 <Button Style="{DynamicResource Esri_ToggleButtonTrayButton}">
   Button
 </Button>

Check Boxes

Default Style: Yes Available Styles:

Style name	Checkbox
Default	Simple check box.
Esri_CheckboxToggleSwitch	Toggle switch check box
Esri_CheckboxTrayButtonHeader	Map and Layout tray buttons toggle check box

If needed, style the individual properties such as Background/Foreground by using Esri brushes.

Default checkbox

<CheckBox Content="CheckBox" Background="{DynamicResource Esri_BackgroundHoverSelectedBrush}" 
        Foreground="{DynamicResource Esri_TextMenuBrush}" 
        BorderBrush="{DynamicResource Esri_BorderHoverBrush}"></CheckBox>

Toggle switch checkbox

<CheckBox Style="{DynamicResource Esri_CheckboxToggleSwitch}"  Content="Toggle Switch"></CheckBox>

Tray buttons toggle check box

<CheckBox Style="{DynamicResource Esri_CheckboxTrayButtonHeader}"></CheckBox>

Colors

Most of the time colors are already set in the default and explicit control styles. For example, you do not need to set the color for a hyperlink control or a button's hover color. When you do need to set a color, make sure you are using an Esri color .

In the majority of cases you will be working with brushes, not with WPF Colors. But in certain situations you may need colors. Esri colors are prefixed with "Esri_Color_". Example: A drop shadow or other highlight color for custom styling of list box items, hover text colors or tooltips.

Available Esri Colors

     <Border BorderBrush="{DynamicResource Esri_TextControlBrush}" BorderThickness="1">
       <Border.Effect>
         <DropShadowEffect Color="{DynamicResource Esri_Color_Gray145}" Opacity="0.4"/>
      </Border.Effect>
     ...
    </Border>

Combo Box

Default Style: Yes

ArcGIS Pro provides default styling for text content of a Combo box control, including mouse over behavior and selection highlight. If needed, style the individual properties such as Background/Foreground by using Esri brushes.

<ComboBox Background="{DynamicResource Esri_BackgroundPressedBrush}" 
          Foreground="{DynamicResource Esri_TextMenuBrush}">
                <ComboBoxItem >Item1</ComboBoxItem>
                <ComboBoxItem >Item2</ComboBoxItem>
                <ComboBoxItem >Item3</ComboBoxItem>
</ComboBox>

DataGrid

Default style: No
Available styles:

Style name	Data grid
Esri_DataGrid	Data Grid
Esri_DataGridHeaderless	Turns off both row and column headers
Esri_DataGridRowHeaderless	Turns off Row headers
Esri_DataGridColumnHeader	Applies style to the data grid column header
Esri_DataGridRowHeader	Applies style to the data grid row header
Esri_DataGridRow	Applies style for the entire row such selection, mouseover, keyboard focus
Esri_DataGridCell	Applies style to the individual cell such as selection, mouseover, border

In a DataGrid control, delete any properties setting the AlternateBackgroundColor. The Esri_DataGrid style sets these properties so they are NOT needed.

  <DataGrid Style="{DynamicResource Esri_DataGrid}"
          ScrollViewer.CanContentScroll="True"      
          AutoGenerateColumns="True"
          HorizontalAlignment="Stretch"
          HeadersVisibility="Column"
          ItemsSource="{Binding Path=GdbDefinitions, Mode=OneWay}">
  ..
  />

Expanders

Default Style: No
Available Styles:

Style name	Expander
Esri_ExpanderBorderless	Expander without a border
Esri_Expander	Expander with a border
Esri_ExpanderGripper	Expander with a gripper
Esri_ExpanderPlus	Expander with a plus button
Esri_ExpanderGripperPlus	Expander with plus button and gripper

Expanders

• Expander without a border

<Expander Style="{DynamicResource Esri_ExpanderBorderless}">
..
 </Expander>

• Expander with a border

<Expander Style="{DynamicResource Esri_Expander}">
..
 </Expander>

• Expander with a gripper

<Expander Style="{DynamicResource Esri_ExpanderGripper}">
..
 </Expander>

• Expander with a plus button

<Expander Style="{DynamicResource Esri_ExpanderPlus}">
..
 </Expander>

• Expander with plus button and gripper

<Expander Style="{DynamicResource Esri_ExpanderGripperPlus}">
..
 </Expander>

Galleries

Default Style: Yes
Available styles: Esri_GalleryItemBackgroundBrush, Esri_TextGalleryItemBrush

Style name	Gallery
Esri_GalleryItemBackgroundBrush	Background brush of the gallery item
Esri_TextGalleryItemBrush	Foreground brush of the gallery item text

Default background and text styling for gallery items

By default, each item in a gallery has a transparent background in the light theme and a dark background in the dark theme in Pro.

Custom background and text styling for gallery items

In some cases, your gallery items will not display clearly in the Dark theme because the items are also dark. You can use the custom Esri Gallery styling in these cases. For example, in ArcGIS Pro the North Arrow gallery for Layouts displays all the items with a white background. If you need a white background for each item in a gallery in dark theme, you can style these items using the following Esri styles:

Esri_GalleryItemBackgroundBrush

Changes the background brush of the gallery item to 'Esri_ControlBackgroundBrush' (white) in Dark and High Contrast Mode. In the light theme it is transparent.

Esri_TextGalleryItemBrush

Changes the foreground brush of the text to a dark gray in light and Dark theme. System color is used in High Contrast mode.

<DataTemplate x:Key="InlineGalleryItemTemplate">
    <Grid Background="{DynamicResource Esri_GalleryItemBackgroundBrush}" ..>
        <Grid.RowDefinitions>
           ...
        </Grid.RowDefinitions>         
          <TextBlock Foreground="{DynamicResource Esri_TextGalleryItemBrush}" .../>
   </Grid>
</DataTemplate>

Hyperlinks

Default Style: Yes

ArcGIS Pro will automatically style a WPF Hyperlink element in an add-in. The styling used by Pro for hyperlinks is listed below.

Style	Type	Weight*	Size*	Color*
	Regular	12pt	Use XAML Hyperlink element	#548953

        <TextBlock>
            <Hyperlink NavigateUri="http://esri.com/">
                  Esri
             </Hyperlink>
        </TextBlock>

Image

Default Style: No

Use this Image style for images displayed on a Tray button UI.

 <Image Source="pack://application:,,,/AddInName;component/Images/TrayButtonImage32.png" 
        Style="{DynamicResource Esri_ImageTrayButton}" Height="32" Width="32"></Image>

Label

Default Style: Yes
Default Font Family: Segoe UI

If needed, style the individual properties such as Background/Foreground by using Esri brushes.

<Label Content="My Label" Background="{DynamicResource Esri_BackgroundPressedBrush}" 
                          Foreground="{DynamicResource Esri_TextControlBrush}"></Label>

List Box

Default style: No
Available Styles:

Style name	List Box
Esri_ListBoxItemHighlightBrush	List box item
Esri_ListBoxPanelIndicator	Horizontal ListBox style for strings with a separator between items

A ListBox control has no default Esri style. You have to use the available List box styles to style a ListBox control. Pro will provide default styling for the list box items if the content is text. This includes mouse over behavior and selection highlight. If the list box items need to be styled, Esri brushes and colors should be used.

List Box with Text items

<ListBox ItemContainerStyle="{DynamicResource Esri_ListBoxItemHighlightBrush}"
         BorderBrush="{DynamicResource Esri_TextControlBrush}" BorderThickness="2">
         ...
</ListBox>

List Box with custom items

 <DataTemplate x:Key="BookmarkListItem" DataType="{x:Type mapping:Bookmark}">
        <StackPanel Orientation="Vertical" Background="Transparent">
          <Image Source="{Binding Thumbnail}"
                                Width="96" Height="96" Stretch="Fill" Margin="5"
                                DockPanel.Dock="Left" ToolTip="{Binding Name}">
            <Image.Effect>
              <DropShadowEffect Color="{DynamicResource Esri_Color_Gray145}" BlurRadius="14" ShadowDepth="4.5">
              </DropShadowEffect>
            </Image.Effect>
          </Image>
          <StackPanel Orientation="Horizontal" Margin="5" >
            <TextBlock Text="{Binding Name}" Margin="5,0,0,0" Style="{DynamicResource RegularText}" />
            <Button x:Name="DeleteButton" Width="16" Height="16"  Margin="0" Style="{DynamicResource Esri_SimpleBorderlessButton}" 
                        ToolTip="{Binding RelativeSource={RelativeSource Mode=FindAncestor, AncestorType=UserControl}, Path=DataContext.DelBookmarkToolTip}"
                        Command="{Binding RelativeSource={RelativeSource Mode=FindAncestor, AncestorType=UserControl}, Path=DataContext.DelBookmarkCommand}" >
              <Image Stretch="None" Width="16" Height="16" VerticalAlignment="Top" Source="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/BookmarkRemove16.png"/>
            </Button>
          </StackPanel>
        </StackPanel>
      </DataTemplate>

List box panel indicator with separators.

The Esri_ListBoxPanelIndicator is a custom horizontal ListBox style for strings that adds a separator between the items and draws custom repeat (scroll) buttons when necessary. The items in the List box are of type TabControl topic20573.html. Override the TabControl's Text property to create strings to add to the list box. You can also override the TabControl class' ToolTip property to provide tooltip information for the items in the Listbox.

This style is often used in conjunction with the TabIndicator control.

XAML definition of the Listbox:

<ListBox x:Name="primaryNavigator" DockPanel.Dock="Left" 
               Style="{DynamicResource Esri_ListBoxPanelIndicator}"
               ItemsSource="{Binding PrimaryMenuList}" 
               SelectedIndex="{Binding SelectedPanelHeaderIndex, Mode=TwoWay}"
               IsSynchronizedWithCurrentItem="True"/>

Initialize the TabControl collection in code:

protected Dockpane1ViewModel() //view model constructor
        {
            PrimaryMenuList.Add(new TabControl() { Text = "PaneHeader1", Tooltip = "PaneHeader1 Tooltip" });
            PrimaryMenuList.Add(new TabControl() { Text = "PaneHeader2", Tooltip = "PaneHeader2 Tooltip" });
            //initialize view model to show content when headers are clicked
            _paneH1VM = new PaneHeader1ViewModel();
            _paneH2VM = new PaneHeader2ViewModel();
            _selectedPanelHeaderIndex = 0;
            CurrentPage = _paneH1VM;
        }

List View

Default style: No
Available Styles:

Style name	List View
Esri_ListBoxItemHighlightBrush	List view item

A List view control has no default Esri style. Pro will provide default styling for the list view items if the content is text. This includes mouse over behavior and selection highlight. If the list view items need to be styled, Esri brushes and colors should be used. To style list view items using an Esri style, use Esri_ListBoxItemHighlightBrush.

<ListView ItemContainerStyle="{DynamicResource Esri_ListBoxItemHighlightBrush}"
         BorderBrush="{DynamicResource Esri_TextControlBrush}" BorderThickness="2">
         ...
</ListView >

Message Boxes

Default Style: Yes

Message boxes cannot be styled. Use ArcGIS.Desktop.Framework.Dialogs.MessageBox to get the Pro look and feel for Message box functionality.

 ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show(
                    "Please add the 'States' layer to the TOC from the Pro community samples AdminData.gdb geodatabase.",
                    "Cannot find US States");

Radio Buttons

Default Style: Yes

If needed, style the individual properties such as Background/Foreground by using Esri brushes.

<RadioButton  Content="Add" Background="{DynamicResource Esri_BackgroundPressedBrush}" 
              Foreground="{DynamicResource Esri_TextInfoBrush}" 
              BorderBrush="{DynamicResource Esri_TextStyleSubduedBrush}"></RadioButton>

Textblocks

Default Style:Yes
Default Font Family: Segoe UI
Style name: See table below

If a style is not specified for a textblock element in an add-in, ArcGIS Pro will use the Esri_TextBlockRegular style. ArcGIS Pro has many TextBlock styles defined that can be used in an add-in. Refer to the table below for the available styles and the appropriate UI text element for which it should be used.

If needed, style the individual properties of the TextBlock such as Background/Foreground by using Esri brushes.

Available Styles

Style	Description
Esri_TextBlockRegular	Default text
Esri_TextBlockH1	H1 Content Header
Esri_TextBlockH2	H2 Sub Content Header
Esri_TextBlockH3	H3 Content Header
Esri_TextBlockH4	H4 Sub Content Header
Esri_TextBlockH5	H5 Expander Header
Esri_TextBlockH6	H6 Input Fields and table>
Esri_TextBlockH7	H7 Sub Text
Esri_TextBlockDockPaneHeading	Dockpane heading
Esri_TextBlockDockPaneHeader	Dockpane Header
Esri_TextBlockDialogHeader	Dialog Header
Esri_TextBlockDialog	Dialog text
Esri_TextBlockBackStageTitle	Backstage title
Esri_TextBlockBackStageHeader	Backstage header
Esri_TextBlockBackStageSubHeader	Backstage SubHeader
Esri_TextBlockBackStageGroupHeader	Backstage group header

TextBlocks

*Brush, Weight and Size are for reference only. Font Styles have the correct color applied and should not be modified.

• Default text

Attribute	Value
Font Family	Segoe UI
Font size	12pt
Font weight	Normal
Foreground brush	Esri_TextStyleDefaultBrush

<TextBlock Style="{DynamicResource Esri_TextBlockRegular}">Default text</TextBlock>

• H1 Content Header

Attribute	Value
Font Family	Segoe UI
Font size	20pt
Font weight	Bold
Foreground brush	Esri_Gray155

<TextBlock Style="{DynamicResource Esri_TextBlockH1}">H1 TextBlock</TextBlock>

• H2 Content Header

Attribute	Value
Font Family	Segoe UI
Font size	15pt
Font weight	Light
Foreground brush	Esri_TextStyleDefaultBrush

<TextBlock Style="{DynamicResource Esri_TextBlockH2}">H2 TextBlock</TextBlock>

• H3 Content Header

Attribute	Value
Font Family	Segoe UI
Font size	14pt
Font weight	SemiBold
Foreground brush	Esri_Gray155

<TextBlock Style="{DynamicResource Esri_TextBlockH3}">H3 TextBlock</TextBlock>

• H4 Content Header

Attribute	Value
Font Family	Segoe UI
Font size	13pt
Font weight	SemiBold
Foreground brush	Esri_Gray145

<TextBlock Style="{DynamicResource Esri_TextBlockH4}">H4 TextBlock</TextBlock>

• H5 Content Header

Attribute	Value
Font Family	Segoe UI
Font size	12pt
Font weight	SemiBold
Foreground brush	Esri_Gray160

<TextBlock Style="{DynamicResource Esri_TextBlockH5}">H5 TextBlock</TextBlock>

• H6 Content Header

Attribute	Value
Font Family	Segoe UI
Font size	11pt
Font weight	Normal
Foreground brush	Esri_Gray155

<TextBlock Style="{DynamicResource Esri_TextBlockH6}">H6 TextBlock</TextBlock>

• H7 Content Header

Attribute	Value
Font Family	Segoe UI
Font size	11pt
Font weight	Light
Foreground brush	Esri_Gray155

<TextBlock Style="{DynamicResource Esri_TextBlockH7}">H7 TextBlock</TextBlock>

Dockpane TextBlocks

• Dockpane heading

Attribute	Value
Font Family	Segoe UI
Font size	15pt
Font weight	Regular
Foreground brush	Esri_TextStyleDefaultBrush

<TextBlock Style="{DynamicResource Esri_TextBlockDockPaneHeading}">Dockpane heading</TextBlock>

• Dockpane header

Attribute	Value
Font Family	Segoe UI
Font size	15pt
Font weight	Regular
Foreground brush	Esri_TextStyleDefaultBrush

<TextBlock Style="{DynamicResource Esri_TextBlockDockPaneHeader}">Dockpane header</TextBlock>

Dialog TextBlocks

• Dialog header

Attribute	Value
Font Family	Segoe UI
Font size	16pt
Font weight	Light
Foreground brush	Esri_Gray145

<TextBlock Style="{DynamicResource Esri_TextBlockDialogHeader}">Dialog header</TextBlock>

• Dialog text

Attribute	Value
Font Family	Segoe UI
Font size	14pt
Font weight	Normal
Foreground brush	Esri_Gray155

<TextBlock Style="{DynamicResource Esri_TextBlockDialog}">Dialog text</TextBlock>

Backstage TextBlocks

• Backstage title

Attribute	Value
Font Family	Segoe UI
Font size	42pt
Font weight	Light
Foreground brush	Esri_TextCaptionActiveBrush

<TextBlock Style="{DynamicResource Esri_TextBlockBackStageTitle}">Backstage title</TextBlock>

• Backstage header

Attribute	Value
Font Family	Segoe UI
Font size	24pt
Font weight	Light
Foreground brush	Esri_TextStyleDefaultBrush

<TextBlock Style="{DynamicResource Esri_TextBlockBackStageHeader}">Backstage header</TextBlock>

• Backstage sub-header

Attribute	Value
Font Family	Segoe UI
Font size	20pt
Font weight	Light
Foreground brush	Esri_TextCaptionActiveBrush

<TextBlock Style="{DynamicResource Esri_TextBlockBackStageSubHeader}">Backstage Sub-Header text</TextBlock>

• Backstage group header

Attribute	Value
Font Family	Segoe UI
Font size	17pt
Font weight	Normal
Foreground brush	Esri_TextStyleDefaultBrush

<TextBlock Style="{DynamicResource Esri_TextBlockBackStageGroupHeader}">Backstage group header</TextBlock>

Tray button textblocks

• Tray button header

Attribute	Value
Font Family	Segoe UI
Font size	14pt
Font weight	Normal
Foreground brush	Esri_TextStyleDefaultBrush

<TextBlock Style="{DynamicResource Esri_TextBlockTrayButtonHeader}">Tray button header</TextBlock>

• Tray button default text

Attribute	Value
Font Family	Segoe UI
Font size	12pt
Font weight	Normal
Foreground brush	Esri_TextStyleDefaultBrush

<TextBlock Style="{DynamicResource Esri_TextBlockTrayButton}">Tray button header</TextBlock>

Textbox

Default Style: Yes
Default Font Family: Segoe UI

If needed, style the individual properties such as Background/Foreground by using Esri brushes.

<TextBox Background="{DynamicResource Esri_BackgroundPressedBrush}" 
         Foreground="{DynamicResource Esri_TextStyleDefaultBrush}"></TextBox>