Xamarin.Android Designer basics

This topic introduces Xamarin.Android Designer features, explains how to launch the Designer, describes the Design Surface, and details how to use the Properties pane to edit widget properties.

Launching the Designer

The Designer is launched automatically when a layout is created, or it can be launched by double-clicking an existing layout file. For example, double-clicking activity_main.axml in the Resources > Layout folder will load the Designer as seen in this screenshot:

Designer screen in Visual Studio

Likewise, you can add a new layout by right-clicking the layout folder in the Solution Explorer and selecting Add > New Item... > Android Layout:

Add New Item dialog

This creates a new .axml layout file and loads it into the Designer.


Newer releases of Visual Studio support opening .xml files inside the Android Designer.

Both .axml and .xml files are supported in the Android Designer.

Designer features

The Designer is composed of several sections that support its various features, as shown in the following screenshot:

Diagram of Designer panes

When you edit a layout in the Designer, you use the following features to create and shape your design:

  • Design Surface – Facilitates the visual construction of the user interface by giving you an editable representation of how the layout will appear on the device. The Design Surface is displayed inside the Design Pane (with the Designer Toolbar positioned above it).

  • Source Pane – Provides a view of the underlying XML source that corresponds to the design presented on the Design Surface.

  • Designer Toolbar – Displays a list of selectors: Device, Version, Theme, layout configuration, and Action Bar settings. The Designer Toolbar also includes icons for launching the Theme Editor and for enabling the Material Design Grid.

  • Toolbox – Provides a list of widgets and layouts that you can drag and drop onto the Design Surface.

  • Properties Window – Lists the properties of the selected widget for viewing and editing.

  • Document Outline – Displays the tree of widgets that compose the layout. You can click an item in the tree to cause it to be selected on the Design Surface. Also, clicking an item in the tree loads the item's properties into the Properties window.

Design Surface

The Designer makes it possible for you to drag and drop widgets from the toolbox onto the Design Surface. When you interact with widgets in the Designer (by either adding new widgets or repositioning existing ones), vertical and horizontal lines are displayed to mark the available insertion points. In the following example, a new Button widget is being dragged to the Design Surface:

Example insertion lines on Design Surface

Additionally, widgets can be copied: you can use copy and paste to copy a widget, or you can drag and drop an existing widget while pressing the CTRL key.

Designer Toolbar

The Designer Toolbar (positioned above the Design Surface) presents configuration selectors and tool menus:

Diagram of Designer Toolbar

The Designer Toolbar provides access to the following features:

  • Alternative Layout Selector – Allows you to select from different layout versions.

  • Device Selector – Defines a set of qualifiers (such as screen size, resolution, and keyboard availability) associated with a particular device. You can also add and delete new devices.

  • Android Version Selector – The Android version that the layout is targeting. The Designer will render the layout according to the selected Android version.

  • Theme Selector – Selects the UI theme for the layout.

  • Configuration Selector – Selects the device configuration, such as portrait or landscape.

  • Resource Qualifier Options – Opens a dialog that presents drop-down menus for selecting Language, UI Mode, Night Mode, and Round Screen options.

  • Action Bar Settings – Configures the Action Bar settings for the layout.

  • Theme Editor – Opens the Theme Editor, which makes it possible for you to customize elements of the selected theme.

  • Material Design Grid – Enables or disables the Material Design Grid. The drop-down menu item adjacent to the Material Design Grid opens a dialog that enables you to customize the grid.

Each of these features is explained in more detail in these topics:

Context menu commands

A context menu is available both in the Design Surface and in the Document Outline. This menu displays commands that are available for the selected widget and its container, making it easier for you to perform operations on containers (which are not always easy to select on the Design Surface). Here is an example of a context menu:

Example context menu when right-clicking the Design Surface

In this example, right-clicking a TextView opens a context menu that provides several options:

  • LinearLayout – opens a submenu for editing the LinearLayout parent of the TextView.

  • Delete, Copy, and Cut – operations that apply to the right-clicked TextView.

Zoom controls

The Design Surface supports zooming via several controls as shown:

Diagram of the Design Surface zoom controls

These controls make it easier to see certain areas of the user interface in the Designer:

  • Highlight Containers – Highlights containers on the Design Surface so that they are easier to locate while zooming in and out.

  • Normal Size – Renders the layout pixel-for-pixel so that you can see how the layout will look at the resolution of the selected device.

  • Fit to Window – Sets the zoom level so that the entire layout is visible on the Design Surface.

  • Zoom In – Zooms in incrementally with each click, magnifying the layout.

  • Zoom Out – Zooms out incrementally with each click, making the layout appear smaller on the Design Surface.

Note that the chosen zoom setting does not affect the user interface of the application at runtime.

Switching between Design and Source panes

In the center strip between the Design and Source panes, there are several buttons that are used to modify how the Design and Source panes are displayed:

Pane display button locations

These buttons do the following:

  • Design – This topmost button, Design, selects the Design pane. When this button is clicked, the Toolbox and Properties panes are enabled and the Text Editor Toolbar is not displayed. When the Collapse button is clicked (see below), the Design pane is presented alone without the Source pane.

  • Swap Panes – This button (which resembles two opposing arrows) swaps the Design and Source panes so that the Source pane is on the left and the Design pane is on the right. Clicking it again swaps these panes back to their original locations.

  • Source – This button (which resembles two opposing angle brackets) selects the Source pane. When this button is clicked, the Toolbox and Properties panes are disabled and the Text Editor Toolbar is made visible at the top of Visual Studio. When the Collapse button is clicked (see below), clicking the Source button displays the Source pane instead of the Design pane.

  • Vertical Split – This button (which resembles a vertical bar), displays the Design and Source panes side-by-side. This is the default arrangement.

  • Horizontal Split – This button (which resembles a horizontal bar), displays the Design pane above the Source pane. Swap Panes can be clicked to place the Source pane above the Design pane.

  • Collapse Pane – This button (which resembles two right-pointing angle brackets) "collapses" the dual-pane display of Design and Source into a single view of one of these panes. This button becomes the Expand Pane button (resembling two left-pointing angle brackets), which can be clicked to return the view back to dual-pane (Design and Source) display mode.

When Collapse Pane is clicked, only the Design pane is displayed. However, you can click the Source button to instead view only the Source pane. Click the Design button again to return to the Design pane.

Source pane

The Source pane displays the XML source underlying the design shown on the Design Surface. Because both views are available at the same time, it is possible to create a UI design by going back and forth between a visual representation of the design and the underlying XML source for the design:

Example XML source in Source Pane

Changes made to the XML source are immediately rendered on the Design Surface; changes made on the Design Surface cause the XML source displayed in the Source pane to be updated accordingly. When you make changes to XML in the Source pane, autocompletion and IntelliSense features are available to speed XML-based UI development as explained next.

For greater navigational ease when working with long XML files, the Source pane supports the Visual Studio scrollbar (as seen on the right in the previous screenshot). For more information about the scrollbar, see How to Track Your Code by Customizing the Scrollbar.


When you begin to type the name of an attribute for a widget, you can press CTRL+SPACE to see a list of possible completions. For example, after entering android:lay in the following example (followed by typing CTRL+SPACE), the following list is presented:

Autocompletion of layout attribute

Press ENTER to accept the first listed completion, or use the arrow keys to scroll to the desired completion and press ENTER. Alternatively, you can use the mouse to scroll to and click the desired completion.


After you enter a new attribute for a widget and begin to assign it a value, IntelliSense pops up after a trigger character is typed and provides a list of valid values to use for that attribute. For example, after the first double-quote is entered for android:layout_width in the following example, an autocompletion selector pops up to provide the list of valid choices for this width:

IntelliSense example for layout width

At the bottom of this popup are two buttons (as outlined in red in the above screenshot). Clicking the Project Resources button on the left restricts the list to resources that are part of the app project, while clicking the Framework Resources button on the right restricts the list to display resources available from the framework. These buttons toggle on or off: you can click them again to disable the filtering action that each provides.

Properties pane

The Designer supports the editing of widget properties through the Properties pane:

Screenshot of the Properties window

The properties listed in the Properties pane change depending on which widget is selected on the Design Surface.

Default values

The properties of most widgets will be blank in the Properties window because their values inherit from the selected Android theme. The Properties window will only show values that are explicitly set for the selected widget; it will not show values that are inherited from the theme.

Referencing resources

Some properties can reference resources that are defined in files other than the layout .axml file. The most common cases of this type are string and drawable resources. However, references can also be used for other resources, such as Boolean values and dimensions. When a property supports resource references, a browse icon (a square) is shown next to the text entry for the property. This button opens a resource selector when clicked.

For example, the following screenshot shows the options available when clicking the darkened square to the right of the text field for a Text widget in the Properties window:

Example list of text options

When Resource... is clicked, the Select Resource dialog is presented:

Example Resources screenshot with several resources listed

From this list, you can select a text resource to use for that widget instead of hard-coding the text in the Properties pane. The next example illustrates the resource selector for the Src property of an ImageView:

Resource selector listing icon resource for an ImageView

Clicking the blank square to the right of the Src property opens the Select Resource dialog with a list of resources ranging from colors (as shown above) to drawables.

Boolean property references

Boolean properties are normally selected as check marks next to a property in the Properties window. You can designate a true or false value by checking or unchecking this check box, or you can select a property reference by clicking the dark-filled square to the right of the property. In the following example, text is changed to all caps by clicking the Text All Caps boolean property reference associated with the selected TextView:

Example of setting boolean properties

Editing properties inline

The Android Designer supports direct editing of certain properties on the Design Surface (so you don't have to search for these properties in the property list). Properties that can be directly edited include text, margin, and size.


The text properties of some widgets (such as Button and TextView), can be edited directly on the Design Surface. Double-clicking a widget will put it into edit mode, as shown below:

Text resource for the hello string

You can enter a new text value or you can enter a new resource string. In the following example, the @string/hello resource is being replaced with the text, CLICK THIS BUTTON:

Shift + Enter to automatically link text to a new resource

This change is stored in the widget's text property; it does not modify the value assigned to the @string/hello resource. When you key in a new text string, you can press Shift + Enter to automatically link the entered text to a new resource.


When you select a widget, the Designer displays handles that allow you to change the size or margin of the widget interactively. Clicking the widget while it is selected toggles between margin-editing mode and size-editing mode.

When you click a widget for the first time, margin handles are displayed. If you move the mouse to one of the handles, the Designer displays the property that the handle will change (as shown below for the layout_marginLeft property):

Screenshot showing margin handles in the Designer

If a margin has already been set, dotted lines are displayed, indicating the space that the margin occupies:

Example of dotted lines marking space around a button


As mentioned earlier, you can switch to size-editing mode by clicking a widget while it is already selected. Click the triangular handle to set the size for the indicated dimension to wrap_content:

Wrap Content and Resize handles

Clicking the Wrap Content handle shrinks the widget in that dimension so that it is no larger than necessary to wrap the enclosed content. In this example, the button text shrinks horizontally as shown in the next screenshot.

When the size value is set to Wrap Content, the Designer displays a triangular handle pointing in the opposite direction for changing the size to match_parent:

Match parent handle

Clicking the Match Parent handle restores the size in that dimension so that it is the same as the parent widget.

Also, you can drag the circular resize handle (as shown in the above screenshots) to resize the widget to an arbitrary dp value. When you do so, both Wrap Content and Match Parent handles are presented for that dimension:

Circular resize handles

Not all containers allow editing the Size of a widget. For example, notice that in the screenshot below with the LinearLayout selected, the resize handles do not appear:

No resize handles

Document Outline

The Document Outline displays the widget hierarchy of the layout. In the following example, the containing LinearLayout widget is selected:

Document Outline example

The outline of the selected widget (in this case, a LinearLayout) is also highlighted on the Design Surface. The selected widget in the Document Outline stays in sync with its counterpart on the Design Surface. This is useful for selecting view groups, which are not always easy to select on the Design Surface.

The Document Outline supports copy and paste, or you can use drag and drop. Drag and drop is supported from the Document Outline to the Design Surface as well as from the Design Surface to the Document Outline. Also, right-clicking an item in the Document Outline displays the context menu for that item (the same context menu that appears when you right-click that same widget on the Design Surface).