Control Customization

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Silverlight enables you to customize controls in several ways. You can customize most controls by modifying its default template. This topic describes the basic concepts you must know in order to either modify the visual appearance of an existing control or to create a new control from scratch.

Custom Control

Custom controls separate the logic from the visual appearance. You use a custom control when you want a strong separation between visual appearance and logic. By doing this, designers can come in later and modify the visual appearance without accessing or modifying the code.

The two ways by which you can modify the appearance of a custom control are by using styles and by modifying the templates (which is also called skinning).


Styles are basically a collection of property settings. Using styles is a way by which you can easily change the visual characteristics of a control. For more information about styles, see Getting Started with Controls.


A template is a XAML file that defines the visual appearance and visual behavior of a control. You can completely replace the appearance of the control by modifying or replacing its default ControlTemplate. You can modify the ControlTemplate to add, rearrange, or delete the parts of a control. The following illustration shows a comparison between two buttons. The first button has a modified style and the second has a modified ControlTemplate.

Button with changed style and control template

Control Contract

Custom controls have a strict separation between the logic and visuals. While this strict separation has benefits, such as customizing the visuals without affecting the logic, it can be challenging for control designers to know what elements the control needs. This is achieved though the control contract. A control contract is an agreement between the logical and the visual parts of the control. In general, a control contract consists of:

  • Visual properties exposed on the control class.

  • Expected parts in the template.

  • Expected logic associated with the parts in the template.

Parts and States Model

Silverlight implements the control contract through a parts and states model. The parts and states model keeps a separation between logic and visuals, while still maintaining an explicit control contract between the designer and the developer. The main concepts in the parts and states model are parts, states, state groups and visual transitions.

You can find the primary named parts and states of a Silverlight control in the Syntax section of the control's class page. For example, you can find the named parts and states of a text box in the Syntax section of the TextBox topic. You can find a more complete list of the parts and states for most controls in the Control Styles and Templates topic. For example, the named parts and states for text box are listed in TextBox Styles and Templates.


Using the parts and states model is the recommended way to create your control, but it is not required by the Silverlight runtime. However, if you want your control to open and render properly in Expression Blend, you must follow the supported parts and states model pattern.


Parts are named elements inside the control template. The control logic expects these parts to be in the control template.

The following illustration shows the parts for the ComboBox control. The ComboBox control has five named parts: ContentPresenter, ContentPresenterBorder, DropDownToggle, ScrollViewer and Popup. Each is programmatically accessed by the control code. When the DropDownToggle is pressed, the Popup is opened and it displays the items in the ComboBox. When you click an item, it is displayed in the ContentPresenter.

ComboBox parts


Visual states are the way the control appears in a particular state. For example, the following illustration shows how a button has a different background color in the Normal, MouseOver and Pressed states.

Button Normal, MouseOver, and Pressed states

State Groups

State groups are a set of mutually exclusive states. Different state groups are orthogonal. This means that a control can be in two different states at the same time only if the states belong to different state groups.

A CheckBox control has four state groups: CommonStates, CheckStates, FocusStates, and ValidationStates. Therefore, a CheckBox can be the in Normal and Checked state at the same time because these states belong to different state groups. But a CheckBox cannot be in Normal and Pressed states at the same time because both these states belong to the CommonStates state group. The following illustration shows CommonStates and CheckStates for CheckBox.

CheckBox state groups

Visual Transitions

Visual transitions represent the visual appearance of a control as it goes from one state to another. In the following illustration, the background of the custom Button gradually changes from a lighter color to a darker color as it goes from the MouseOver to the Pressed state.

Button transitioning between states

Next Steps

To learn how you can modify the appearance of an existing control see Customizing the Appearance of an Existing Control by Using a ControlTemplate. To create a new custom control from scratch by creating a ControlTemplate, see Creating a New Control by Creating a ControlTemplate.You can find the default styles and templates of controls in Control Styles and Templates.