# Image

‘image’ is used to insert and display an image within a component.

## Example

```python
from deephaven import ui

img = ui.image(src="https://i.imgur.com/Z7AzH2c.png", alt="Sky and roof")
```

## UI Recommendations

1. Provide descriptive alt text for all images to ensure accessibility for users with visual impairments. Note: If the image is considered decorative and should not be announced by screen readers, then set alt=”” to suppress the warning.
2. Alt text should convey the purpose and content of the image. For example, “Snow-capped mountains under a clear blue sky” or “Diagram illustrating the water cycle, showing evaporation, condensation, precipitation, and collection”.
3. To internationalize an image, a localized string should be passed into the alt prop.

## Visual options

Different styles determine how an image fits into its container. The default value for the `object_fit` parameter is `fill`, which takes up the whole dimension of the container.

Other options:

- `contain` scales the image to the dimension of the container while preserving its aspect ratio. If the image’s aspect ratio does not match the aspect ratio of the box, the image will be “letterboxed”.
- `cover` scales the image to fill the entire container. If the image’s aspect ratio does not match the aspect ratio of the box, the image will be clipped to fit.
- `none` renders the image in its original dimensions.
- `scale-down` sizes the image as if `none` or `contain` were specified. Whichever results in a smaller concrete image size is selected.

```python
def image_variants():
    return ui.flex(
        ui.view(
            ui.image(src="https://i.imgur.com/Z7AzH2c.png", alt="Sky and roof"),
            background_color="celery-600",
            padding="10px",
        ),
        ui.view(
            ui.image(
                src="https://i.imgur.com/Z7AzH2c.png",
                alt="Sky and roof",
                object_fit="contain",
            ),
            background_color="blue-600",
            padding="10px",
            padding_x="25px",
        ),
        ui.view(
            ui.image(
                src="https://i.imgur.com/Z7AzH2c.png",
                alt="Sky and roof",
                object_fit="cover",
            ),
            background_color="blue-600",
            width="75%",
        ),
        ui.view(
            ui.image(
                src="https://i.imgur.com/Z7AzH2c.png",
                alt="Sky and roof",
                object_fit="none",
            )
        ),
        ui.view(
            ui.image(
                src="https://i.imgur.com/Z7AzH2c.png",
                alt="Sky and roof",
                object_fit="scale-down",
            )
        ),
        direction="column",
        width="300px",
    )


image_variants_example = image_variants()
```

## API Reference

Image is used to insert and display an image within a component.

**Returns:** `Element` The rendered Image element.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "image", "parameters": [{"name": "src", "type": "str", "description": "The URL of the image."}, {"name": "alt", "type": "str | None", "description": "Text description of the image.", "default": "None"}, {"name": "object_fit", "type": "Literal['fill', 'contain', 'cover', 'none', 'scale-down']", "description": "How the image should be resized to fit its container.", "default": "'fill'"}, {"name": "on_error", "type": "Callable[[], None] | None", "description": "A callback function to run when the image fails to load.", "default": "None"}, {"name": "on_load", "type": "Callable[[], None] | None", "description": "A callback function to run when the image has loaded.", "default": "None"}, {"name": "flex", "type": "str | float | bool | None", "description": "When used in a flex layout, specifies how the element will grow or shrink to fit the space available.", "default": "None"}, {"name": "flex_grow", "type": "float | None", "description": "When used in a flex layout, specifies how the element will grow to fit the space available.", "default": "None"}, {"name": "flex_shrink", "type": "float | None", "description": "When used in a flex layout, specifies how the element will shrink to fit the space available.", "default": "None"}, {"name": "flex_basis", "type": "str | float | None", "description": "When used in a flex layout, specifies the initial main size of the element.", "default": "None"}, {"name": "align_self", "type": "Literal['auto', 'normal', 'start', 'end', 'center', 'flex-start', 'flex-end', 'self-start', 'self-end', 'stretch'] | None", "description": "Overrides the alignItems property of a flex or grid container.", "default": "None"}, {"name": "justify_self", "type": "Literal['auto', 'normal', 'start', 'end', 'flex-start', 'flex-end', 'self-start', 'self-end', 'center', 'left', 'right', 'stretch'] | None", "description": "Species how the element is justified inside a flex or grid container.", "default": "None"}, {"name": "order", "type": "int | None", "description": "The layout order for the element within a flex or grid container.", "default": "None"}, {"name": "grid_area", "type": "str | None", "description": "When used in a grid layout, specifies the named grid area that the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "When used in a grid layout, specifies the row the element should be placed in within the grid.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "When used in a grid layout, specifies the column the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting row to span within the grid.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending row to span within the grid.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting column to span within the grid.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending column to span within the grid", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin for all four sides of the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin for the top side of the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin for the bottom side of the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin for the logical start side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin for the logical end side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin for the left and right sides of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin for the top and bottom sides of the element.", "default": "None"}, {"name": "width", "type": "str | float | None", "description": "The width of the element.", "default": "None"}, {"name": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width of the element.", "default": "None"}, {"name": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height of the element.", "default": "None"}, {"name": "max_height", "type": "str | float | None", "description": "The maximum height of the element", "default": "None"}, {"name": "position", "type": "Literal['static', 'relative', 'absolute', 'fixed', 'sticky'] | None", "description": "The position of the element.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The distance from the top of the containing element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The distance from the bottom of the containing element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The distance from the left of the containing element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The distance from the right of the containing element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The distance from the start of the containing element, depending on layout direction.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element, depending on layout direction.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stack order of the element.", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Whether the element is hidden.", "default": "None"}, {"name": "id", "type": "str | None", "description": "The unique identifier of the element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "A CSS class to apply to the element.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "A CSS style to apply to the element.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />