XAML Previewer for Xamarin.Forms

See your Xamarin.Forms layouts rendered as you type!

Requirements

Projects require the latest Xamarin.Forms NuGet package for the XAML Previewer to work. Previewing Android apps requires JDK 1.8 x64.

There is more information in the release notes.

Getting started

The Xamarin.Forms XAML Previewer shows a platform-specific preview of your XAML file in real time, while you edit it.

Visual Studio

The XAML Previewer is available by expanding the split view pane. Default split view behavior can be controlled from the Tools > Options > Xamarin > Forms Previewer dialog. In this dialog, you can select the default document view and the split orientation.

Xamarin.Forms Previewer options in Visual Studio

When opening a XAML page, the editor will split based on the settings selected in the Tools > Options > Xamarin > Forms Previewer dialog. However, the split can be changed for each file in the editor window.

XAML preview controls

The top of the editor window has buttons to select which pane is in use, with the top button switching to the design pane and the bottom button switching to the source pane. The middle button swaps the pane order.

Xamarin.Forms Previewer controls to switch between design, source, and split view in Visual Studio

The bottom of the editor window has buttons to vertically and horizontally split the panes, and to expand or collapse the current sub-pane.

Xamarin.Forms Previewer pane orientation controls in Visual Studio

Visual Studio for Mac

The Preview button is displayed on the editor when you open a XAML page. The preview pane can be shown or hidden by pressing the Preview button in the top-right corner of any XAML document window:

Xamarin.Forms Previewer in Visual Studio for Mac

Visual Studio 2019 (Preview)

The XAML Previewer is available by expanding the split view pane. Default split view behavior can be controlled from the Tools > Options > Xamarin > Forms Previewer dialog. In this dialog, you can select the default document view and the split orientation.

Xamarin.Forms Previewer options in Visual Studio

When opening a XAML page, the editor will split based on the settings selected in the Tools > Options > Xamarin > Forms Previewer dialog. However, the split can be changed for each file in the editor window.

XAML preview controls

The top of the editor window has buttons to select which pane is in use, with the top button switching to the design pane and the bottom button switching to the source pane. The middle button swaps the pane order.

Xamarin.Forms Previewer controls to switch between design, source, and split view in Visual Studio

The bottom of the editor window has buttons to vertically and horizontally split the panes, and to expand or collapse the current sub-pane.

Xamarin.Forms Previewer pane orientation controls in Visual Studio

XAML previewer options

The options along the top of the preview pane are:

  • Phone – preview on a phone sized screen
  • Tablet - preview on a tablet sized screen
  • Android – show the Android version of the screen
  • iOS – show the iOS version of the screen (Note: If you're using Visual Studio on Windows, you must be paired to a Mac to use this mode)
  • Portrait (icon) – uses portrait orientation for the preview
  • Landscape (icon) – uses landscape orientation for the preview

Device drop-down menu

In Visual Studio 2019 (Preview), you can select a device to preview on from a drop-down list of Android or iOS devices. This drop-down replaces the "Phone" and "Tablet" options. When previewing iOS, the drop-down will show iPhone and iPad devices. When previewing Android, the drop-down will show various Android phones and tablets. Both lists include screen sizes and screen resolutions.

Detect design mode

The static DesignMode.IsDesignModeEnabled property can be examined to determine whether the application is running in the previewer. This allows you to specify code that will only execute when the application is running in the previewer:

if (DesignMode.IsDesignModeEnabled)
{
  // Previewer only code  
}

Enable design time rendering for custom controls

Custom controls have to opt-in to design time rendering to appear in the previewer, regardless of whether the control resides in your project, or is imported from a library. This can be accomplished by adding the [DesignTimeVisible(true)] to your control's class:

namespace MyProject
{
  [DesignTimeVisible(true)]
  public class MyControl : BaseControl
  {
    // Your control's code here
  }

}

An example of this can be seen in James Montemagno's ImageCirclePlugin's base class.

Add design-time data

Some layouts may be hard to visualize without any data bound to the user interface controls. To make the preview more useful, assign some static data to the controls by hardcoding a binding context (either in the code-behind or using XAML).

Refer to James Montemagno's blog post on adding design-time data to see how to bind to a static ViewModel in XAML.

Troubleshooting

Check the issues below, and the Xamarin Forums, if you encounter problems.

XAML Previewer isn't showing or shows an error

Check the following:

  • The Designer Agent must be set-up the first time you preview a XAML file - a progress indicator will appear in the Previewer, along with progress messages, until this is ready.
  • Try closing and re-opening the XAML file.
  • Ensure that your App class has a parameterless constructor.

Custom controls aren't rendering

Ensure that your project is built. If the previewer can't render the control without an error, or the control's creator did not opt-in to design time rendering, the previewer shows the control's base class.