This documentation is archived and is not being maintained.

Image Class

Represents a control that displays an image.

Namespace:  System.Windows.Controls
Assembly:  PresentationFramework (in PresentationFramework.dll)

[LocalizabilityAttribute(LocalizationCategory::None, Readability = Readability::Unreadable)]
public ref class Image : public FrameworkElement, 

The Image class enables you to load the following image types: .bmp, .gif, .ico, .jpg, .png, .wdp, and .tiff.

When displaying a multiframe image, only the first frame is displayed. The animation of multiframe images is not supported by the Image control.

Until the image content is loaded, the ActualWidth and ActualHeight of the control will report as zero, because the image content is used to determine the final size and location of the control.

For a fixed size control, the Width and/or Height properties can be set. However, to preserve the media's aspect ratio, set the Width or Height properties but not both.

This example shows how to include images in an application by using the Image element.

The following example shows how to render an image 200 pixels wide. In this Extensible Application Markup Language (XAML) example, both attribute syntax and property tag syntax are used to define the image. For more information on attribute syntax and property syntax, see Dependency Properties Overview. A BitmapImage is used to define the image's source data and is explicitly defined for the property tag syntax example. In addition, the DecodePixelWidth of the BitmapImage is set to the same width as the Width of the Image. This is done to ensure that the minimum amount of memory is used rendering the image.


In general, if you want to specify the size of a rendered image, specify only the Width or the Height but not both. If you only specify one, the image's aspect ratio is preserved. Otherwise, the image may unexpectedly appear stretched or warped. To control the image's stretching behavior, use the Stretch and StretchDirection properties.


When you specify the size of an image with either Width or Height, you should also set either DecodePixelWidth or DecodePixelHeight to the same respective size.

The Stretch property determines how the image source is stretched to fill the image element. For more information, see the Stretch enumeration.

<!-- Simple image rendering. However, rendering an image this way may not
     result in the best use of application memory. See markup below which
     creates the same end result but using less memory. -->
<Image Width="200" 
Source="C:\Documents and Settings\All Users\Documents\My Pictures\Sample Pictures\Water Lilies.jpg"/>

<Image Width="200">
    <!-- To save significant application memory, set the DecodePixelWidth or  
     DecodePixelHeight of the BitmapImage value of the image source to the desired 
     height and width of the rendered image. If you don't do this, the application will 
     cache the image as though it were rendered as its normal size rather then just 
     the size that is displayed. -->
    <!-- Note: In order to preserve aspect ratio, only set either DecodePixelWidth
         or DecodePixelHeight but not both. -->
    <BitmapImage DecodePixelWidth="200"  
     UriSource="C:\Documents and Settings\All Users\Documents\My Pictures\Sample Pictures\Water Lilies.jpg" />

The following example shows how to render an image 200 pixels wide using code.


Setting BitmapImage properties must be done within a BeginInit and EndInit block.

No code example is currently available or this language may not be supported.

More Code

How to: Crop an Image This example shows how to crop an image using CroppedBitmap.
How to: Rotate an Image This example shows how to rotate an image 90 degrees by using a Rotation property of a BitmapImage.
How to: Convert an Image to Greyscale This example shows how to convert an image to grayscale using FormatConvertedBitmap.
How to: Use a Drawing as an Image Source This example shows how to use a Drawing as the Source for an Image control. To display a Drawing with an Image control, use a DrawingImage as the Image control's Source and set the DrawingImage object's DrawingImage::Drawing property to the drawing you want to display.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0