Image

Inherits from Xamarin.Forms.ContentView

If you'd like to show an animated GIF, use the default Image control instead.

One of the most common controls you'll want to use is the Image control. Because of its importance, effort has been invested into ensuring that it has all the power you need. Let's start with the basics.

<Rock:Image Source="https://server.com/photo.jpg" />

Is that it? No, we're just getting started. Below are all of the properties you can add to images.

Basic Image

Properties

Property	Type	Description
Aspect	Aspect	Determines how the image will fill the space allotted. Valid values are: AspectFill - Fill the space with the image, some parts of the image may be cropped. AspectFit - Scale the image to fit the space, some parts of the space may be left empty. Fill - Scale the image to exactly fill the space, this may warp the image.
BackgroudColor	Color	The color to use for the background. This is useful if you'd like to show a placeholder color while the image downloads.
Command	ICommand	The command to execute when the user taps on the image.
CommandParameter	object	The parameters to pass to the command when it's executed.
ErrorPlaceholder	string	The URL of the image to display if an error occurred trying to load the main image.
HeightRequest	int	The height you'd like your image to be.
WidthRequest	int	The width you'd like your image to be.
HorizontalOptions	LayoutOption	This describes how the element is laid out horizontally within the parent , and how this element should consume leftover space on the X axis. Common values would be: Center - centered and does not expand. FillAndExpand - Fills the whole area.
LoadingPlaceholder	string	The URL of the image to use as a loading placeholder while the main image loads. This image will need to be loaded once and then due to caching it will be available to all Image tags.
Ratio	string	Determines the size of the image based on the width of the parent container. The format is height:width (e.g. '4:2').
Source	string	The URL of the image to be loaded and displayed.
VerticalOptions	LayoutOption	This describes how the element is laid out vertically within the parent , and how this element should consume leftover space on the Y axis.
Margin	Thickness	Images, like most controls can have margins. This is typically note as Margin="Left,Top,Right,Bottom".

Done now? Nope, still have much more to consider.

Image Transformations

You can apply several different transformations to your images. Each is discussed below.

Blur

You can easily add a blur to your image with this simple transformation.

Blurring is a very CPU-intensive operation. The higher the radius value the more intensive this becomes. Use caution to not over blur something dynamically when you can instead replace it with a statically blurred image. Android devices have been known to crash with radius values over 15 or so.

Property	Type	Description
Radius	Float	The amount of blur to add.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:BlurTransformation Radius="4" />
</Rock:Image>

Blur Transform

Circle

The circle transformation masks your images into a circle shape. The syntax for this is below.

Property	Type	Description
BorderSize	int	The size of the optional border around the image.
BorderColor	Color	The color of the border around the image.

<Rock:Image 
    Source="https://server.com/photo.jpg" 
    BackgroundColor="#c4c4c4"
    HeightRequest="128"
    WidthRequest="128"
    Aspect="AspectFill" 
    HorizontalOptions="Center" 
    VerticalOptions="Fill">
    <Rock:CircleTransformation BorderSize="4" 
        BorderColor="rgba(255, 255, 255, 0.58)" />
</Rock:Image>

Circle Transform

Drop Shadow

The filter adds a customizable drop shadow to your images.

Property	Type	Description
Distance	double	Determines how far the drop shadow should extend below the image.
Angle	double	Sets the direction the drop shadow should extend from.
Radius	double	Determines the level of blur the drop shadow should use.
Color	Color	The color of the drop shadow.
Opacity	double	The opacity of the shadow.

When using the drop shadow transformation be sure you do not have a background color. Otherwise, the background color will cover the drop shadow.

<Rock:Image 
    Source="https://server.com/photo.jpg" 
    BackgroundColor="#c4c4c4"
    HeightRequest="300"
    WidthRequest="300"
    Aspect="AspectFill" 
    HorizontalOptions="Center" 
    VerticalOptions="Fill">
    <Rock:DropShadowTransformation 
        Distance="8"
        Angle="135"
        Radius="4"
        Color="#c4c4c4"
        Opacity="0.5" />
</Rock:Image>

Drop Shadow Transformation

Fill Color

This fills the image with the selected color. Not sure why you'd ever use this? Well, there's a great usage for this when used with Masks on layered images.

Property	Type	Description
Color	Color	The color to fill the image with.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:FillColorTransformation Color="#41BFD0" />
</Rock:Image>

Fill Transformation

Flip

Flips the image either horizontally, vertically, or both.

Property	Type	Description
Direction	FlipDirection	Valid values include: Horizontal, Vertical or Both

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:FlipTransformation Direction="Both" />
</Rock:Image>

Flip Transformation

Grayscale

Converts the image to grayscale.

Property	Type	Description
Saturation	double	Determines this level of color saturation. A value of 1.0 will not change the original image. Using 0.0 will make the image fully gray scale. You can also provide -1.0 to invert the image.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:GrayscaleTransformation Saturation="0" />
</Rock:Image>

Grayscale Transformation

Reflection

Draws a reflection of the image as if the image were sitting on a glass surface.

Property	Type	Description
Size	double	The size of the reflection.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:ReflectionTransformation Size="96" />
</Rock:Image>

Reflection Transformation

Rounded

Rounds the corners of the image and optionally adds a border.

Property	Type	Description
CorderRadius	CornerRadius	You can provide a specific radius for each corner, or provide one value to be used for all of them.
BorderSize	float	The size of the border to optionally apply.
BorderColor	Color	The color of the border to apply.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:RoundedTransformation CornerRadius="120, 0, 0, 120" 
        BorderSize="4" 
        BorderColor="rgba(255, 255, 255, 0.58)" />
</Rock:Image>

Rounded Transformation

Tint

Tints the image using the provided color.

Property	Type	Description
Color	Color	The color to use to tint the mid-tones of the image.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:TintTransformation Color="#41BFD0" />
</Rock:Image>

Tint Transformation

Keep in mind you can use more than one transformation on a single image.

Now are we done? Not quite, what's the rush?

Layering Images

Want to go to the next level with your images? Layer them! Look at the sample below:

<Grid>
    <!-- Bottom image -->
    <Rock:Image Source="https://server.com/photo.jpg" 
        Aspect="Fill"
        HeightRequest="360"
        HorizontalOptions="FillAndExpand">
        <Rock:TintTransformation Color="#53AFBE" />
    </Rock:Image>
    
    <!-- Top mask -->
    <Rock:Image Source="resource://Rock.Mobile.Resources.Masks.vignette.png" 
         Aspect="Fill"
         HeightRequest="360"
         HorizontalOptions="FillAndExpand">
         <Rock:FillColorTransformation Color="#53AFBE" />
     </Rock:Image>
</Grid>

Results of Layering Images

To make this, simply stack the original mountain under one of our built-in Masks. Note how the mask is just a PNG with an alpha channel. Notice how the mask is black. Applying a Fill Color transformation allows us to match the tint we added to the mountain photo producing a nice color vignette effect.

Styling

Ratio vs. HeightRequest

While HeightRequest can be used to size images, using Ratio is preferred.

<Rock:Image 
    Source="https://server.com/photo.jpg"
    Ratio="4:2" />