# Image

## Overview

The Image component is a fundamental visual element for:

```
-   Displaying static images (e.g., logos, product photos).
-   Displaying dynamic images based on data from Salesforce (e.g., showing a Contact's profile picture).
-   Creating visually rich user interfaces.
```

### Use Cases

* Record Detail Pages: Display a product image, a user's profile picture, a company logo, or other relevant images associated with a record.
* Dashboards: Include images in dashboards to provide visual context or branding.
* Catalogs: Create visually appealing product catalogs.
* Image Galleries: Display a series of images (though specialized components like Carousel might be better suited for this).
* Marketing Content: Include images to make your components more engaging.

## Configuring the Image Component

Select the Image component on the canvas to access its properties in the Properties Panel.

### Basic Properties

* **API Name:** (Text) A unique identifier for this component instance (e.g., `ProductImage`, `UserProfilePicture`).
* **Image Source:** (Text - *Crucial*) This property determines *the image's origin*. You have several options, selectable via the resource selector icon:
  * **Static URL:** Enter the *full URL* of an image hosted online (e.g., `https://www.example.com/myimage.jpg`). *Important:* The image must be publicly accessible or accessible to your Salesforce users based on their sharing settings.
  * **Resource:** Select a *Static Resource* from your Salesforce org. This is the recommended way to include images in your application's design. You must upload the picture as a Static Resource in Salesforce Setup *before* you can select it here.
  * **Variable/Formula:** Use a Text Variable or Formula resource that *returns a URL string*. This allows you to change the image based on data or user interaction dynamically. Example: Display a different product image based on the selected product in a Data Table.
  * **Component Attribute:** Dynamically retrieve the URL from another component's attribute.
* **Alternative Text (alt):** (Text - *Essential for Accessibility*) Provide a short, descriptive text alternative for the image. Screen readers use this text for visually impaired users and is also displayed if the image fails to load. *Always provide meaningful alt text.*

### Size and Positioning

* **Width:** (Text/Number) Controls the width of the image. Best Practice: Set *either* Width *or* Height, but usually not both, to avoid distortion. Options:
  * **Number + `px`:** Specify a width in pixels (e.g., `100px`, `250px`).
  * **Number + `%`:** Specify a width as a percentage of the *containing element's* width (e.g., `50%`, `100%`).
  * **`auto`:** The image's intrinsic width will be used.
  * **Blank:** Let the browser determine the best fit based on other settings.
* **Height:** (Text/Number) Controls the height of the image. Best Practice: Set *either* Width *or* Height, but usually not both, to avoid distortion. Options:
  * **Number + `px`:** Specify a height in pixels.
  * **Number + `%`:** Specify a height as a percentage of the *containing element's* height.
  * **`auto`:** The image's intrinsic height will be used.
  * **Blank:** Let the browser determine the best fit based on other settings.
* **Crop Fit:** (Text - Select from options) Determines how the image is resized or cropped to fit within the specified `Width` and `Height` (if set). This is crucial for controlling the image's behavior when its aspect ratio doesn't match the component's dimensions.
  * `cover`: The image is scaled to cover the component area completely, *maintaining its aspect ratio*. Parts of the image may be *cropped* if the aspect ratios don't match. This is often the best choice for background images.
  * `contain`: The image is scaled to *fit entirely within* the component area, *maintaining its aspect ratio*. There may be *empty space* around the image if the aspect ratios don't match. This is often the best choice for displaying images without cropping.
  * `fill`: The image is *stretched or squashed* to *exactly fill* the component area, *without* maintaining its aspect ratio. This can lead to *distortion*. Avoid this unless you specifically want a stretched/squashed effect.
  * `none`: The image is displayed at its *original size*. If it's larger than the component area, it will be *clipped*.
* **Crop Size:** (Text - Select from Options): Determines the size of the cropping area.
  * `x-small`
  * `small`
  * `medium`
  * `large`
  * `x-large`
  * `2x-large`
  * `3x-large`
  * `4x-large`
* **Crop Position X:** (Text - Select from options) Moves the crop horizontally.
  * `left`
  * `center`
  * `right`
* **Crop Position Y:** (Text - Select from options) Moves the crop vertically.
  * `Top`
  * `Center`
  * `Bottom`
* **Position:** (Text - Select from options) Determines how the image is positioned if it doesn't fill the entire component area. Options often include:
  * `static`
  * `relative`
  * `absolute`
  * `fixed`

### Behavior

* **Magnifier Type:** (Text - Select from options) Adds magnification.
  * `None` (Default)
  * `standard`
  * `follow`
* **Visible:** (Boolean) Controls whether the Image component is visible on the page. Bind this to a Boolean Variable or Formula for dynamic visibility.
* **Disabled** (Boolean - Checkbox): If set to true, disable the component

## Examples

### Example 1: Static Image from a URL

```
-   Image Source:  `https://www.example.com/logo.png`
-   Width:  `200px`
-   Height:  `auto`
-   Crop Fit:  `contain`
-   Source:  Company Logo
```

This would display the image from the URL, setting a fixed width of 200 pixels and automatically adjusting the height to maintain the aspect ratio.

### Example 2: Dynamic Image from a Record (on an Account Record Page)

```
-   Image Source:  `$Component.record.PhotoUrl`  (This assumes the Account object has a field named `PhotoUrl` containing the image URL)
-   Width: `100%`
-   Height: `auto`
-   Crop Fit: `cover`
-   Source:  Account Photo
```

If the [**Target Object Page**](https://docs.avonnicomponents.com/dynamic-components/getting-started/understanding-the-essentials/target-page-object) is set to `Account`, you can bind the `Image Source` to `$Component.record.PhotoUrl` to display the current Account's photo. Setting `Width` to `100%` and leaving `Height` blank (or `auto`) preserves the aspect ratio, while `Crop Fit: cover` ensures the image fills the available space, potentially cropping it.

### Example 3: Display an Image from a variable.

1. Create a variable named `imageUrl` of type text.
2. Add a "On Load" interaction to set the variable value with a static image URL.
3. Add an image component.
4. Set the `Image Source` to the variable value, `@imageUrl`
5. Important Considerations
   * Image URLs: If using URLs, ensure they are valid and accessible to the users.
   * Static Resources: For images that are part of your application's design, using Static Resources is generally recommended for performance and security.
   * Aspect Ratio: Be mindful of the image's aspect ratio and how you set the `Width`, `Height`, and `Crop Fit` properties to avoid distortion.
   * Accessibility: *Always* provide meaningful alternative text in the `Source` property.
   * Dynamic Images: Leverage the ability to bind `Image Source` to Variables and Formulas to create dynamic image displays.

## In Summary

The image component is a simple yet powerful component that allows you to enhance any dynamic component by adding an image from different sources. You can adjust the size, position, and crop and add a magnifier.