Edit

Render Custom Controls in the XAML Previewer

  • Article

Custom controls sometimes don't work as expected in the XAML Previewer. Use the guidance in this article to understand the limitations of previewing your custom controls.

Warning

The XAML Previewer has been deprecated in Visual Studio 2019 version 16.8 and Visual Studio for Mac version 8.8, and replaced by the XAML Hot Reload feature in Visual Studio 2019 version 16.9 and Visual Studio for Mac version 8.9. Learn more about XAML Hot Reload in the documentation.

Basic Preview mode

Even if you haven't built your project, the XAML Previewer will render your pages. Until you build, any control that relies on code-behind will show its base Xamarin.Forms type. When your project is built, the XAML Previewer will try to show custom controls with design time rendering enabled. If the render fails, it will show the base Xamarin.Forms type.

Enable design time rendering for custom controls

If you make your own custom controls, or use controls from a third-party library, the Previewer might display them incorrectly. Custom controls must opt in to design time rendering to appear in the previewer, whether you wrote the control or imported it from a library. With controls you've created, add the [DesignTimeVisible(true)] to your control's class to show it in the Previewer:

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

}

Use James Montemagno's ImageCirclePlugin's base class as an example.

SkiaSharp controls

Currently, SkiaSharp controls are only supported when you're previewing on iOS. They won't render on the Android preview.

Troubleshooting

Check your Xamarin.Forms version

Make sure you have at least Xamarin.Forms 3.6 installed. You can update your Xamarin.Forms version on NuGet.

Even with [DesignTimeVisible(true)], my custom control isn't rendering properly.

Custom controls that rely heavily on code-behind or backend data don't always work in the XAML Previewer. You can try:

The XAML Previewer shows the error "Custom Controls aren't rendering properly"

Try cleaning and rebuilding your project, or closing and reopening the XAML file.