App Factory

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.

Properties

PropertyTypeDescription

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.

PropertyTypeDescription

Radius

Float

The amount of blur to add.

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

Circle

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

PropertyTypeDescription

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>

Drop Shadow

The filter adds a customizable drop shadow to your images.

PropertyTypeDescription

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>

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.

PropertyTypeDescription

Color

Color

The color to fill the image with.

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

Flip

Flips the image either horizontally, vertically, or both.

PropertyTypeDescription

Direction

FlipDirection

Valid values include: Horizontal, Vertical or Both

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

Grayscale

Converts the image to grayscale.

PropertyTypeDescription

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>

Reflection

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

PropertyTypeDescription

Size

double

The size of the reflection.

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

Rounded

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

PropertyTypeDescription

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>

Tint

Tints the image using the provided color.

PropertyTypeDescription

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>

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>

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" />

Last updated

Resources

Release NotesCommunity ChatAsk Chip

Documentation

Rock ManualsLava

⚙️ Powered by Rock RMS