# Image

> Bitmaps with fit, opacity, radius; a pan-and-zoom viewer. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/image/

:::tip[In plain words]
Shows a picture from a file: a photo, a logo, a screenshot.
:::

`pz.image(source)` shows a PNG, JPEG, GIF, WebP, BMP… from a path, `bytes`, or raw RGBA pixels with `size=(w, h)`. Options: `content_fit` (`"contain"`, `"cover"`, `"fill"`, `"none"`, `"scale_down"`), `filter` (`"linear"` or `"nearest"`), `opacity`, `radius`, `rotation` and `scale`. `pz.image_viewer` adds pan (drag) and zoom (wheel).

`pz.image` · Category: [Content](https://albakore.github.io/pyzed/library/#content) · [Full reference →](https://albakore.github.io/pyzed/reference/widgets/#image)

**Code:**

```python
pz.row([
    pz.image("photo.png", width=300, height=180, content_fit="cover", radius=10),
    pz.image("photo.png", width=140, height=180, content_fit="contain", opacity=0.5),
], spacing=16, align="center")
```

## When to use

- For screenshots, avatars, thumbnails and photo viewers.

## Usage

```python
import pyzed as pz

pz.row([
    pz.image("photo.png", width=300, height=180, content_fit="cover", radius=10),
    pz.image("photo.png", width=140, height=180, content_fit="contain", opacity=0.5),
], spacing=16, align="center")
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### Fit

```python
pz.image("photo.png", width=200, height=110, content_fit="cover")
```

```python
pz.image("photo.png", width=200, height=110, content_fit="contain")
```

```python
pz.image("photo.png", width=200, height=110, content_fit="fill")
```

### Look

`rotation` is in degrees, clockwise; the corners of a rotated image may reach outside its box.

```python
pz.image("photo.png", width=200, height=110, content_fit="cover", radius=16)
```

```python
pz.image("photo.png", width=200, height=110, content_fit="cover", opacity=0.4)
```

```python
pz.image("photo.png", width=200, height=110, content_fit="cover", radius=10, rotation=8)
```

## Events

Image has no events of its own: it shows what you give it. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

## Properties and API

### `pz.image`

```python
image(
    source,
    *,
    width=None,
    height=None,
    content_fit=None,
    filter='linear',
    opacity=1.0,
    radius=0.0,
    rotation=0.0,
    scale=1.0,
    size=None,
)
```

A bitmap image (PNG, JPEG, GIF, BMP, WebP…) from a path or `bytes`, or raw RGBA pixels.

| Property | Default | Description |
| --- | --- | --- |
| `source` | *required* | File path, `bytes` of the encoded file, or raw RGBA pixels with `size=(width, height)`. |
| `width` | `None` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | `None` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `content_fit` | `None` | `"contain"`, `"cover"`, `"fill"`, `"none"` or `"scale-down"`. |
| `filter` | `"linear"` | `"linear"` (smooth) or `"nearest"` (crisp pixels, for pixel art). |
| `opacity` | `1.0` | Opacity from 0 to 1. |
| `radius` | `0.0` | Corner radius. |
| `rotation` | `0.0` | Rotation in degrees. |
| `scale` | `1.0` | Scale. |
| `size` | `None` | `(width, height)` when `source` is raw RGBA pixels. |

[Full reference →](https://albakore.github.io/pyzed/reference/widgets/#image)

### `pz.image_viewer`

```python
image_viewer(
    source,
    *,
    width=None,
    height=None,
    min_scale=0.25,
    max_scale=10.0,
    scale_step=0.1,
    filter='linear',
    size=None,
)
```

An image you can pan (by dragging) and zoom (mouse wheel), like Iced's viewer.

| Property | Default | Description |
| --- | --- | --- |
| `source` | *required* | File path, `bytes` of the encoded file, or raw RGBA pixels with `size=(width, height)`. |
| `width` | `None` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | `None` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `min_scale` | `0.25` | Minimum zoom. |
| `max_scale` | `10.0` | Maximum zoom. |
| `scale_step` | `0.1` | How much the zoom changes per wheel step. |
| `filter` | `"linear"` | `"linear"` (smooth) or `"nearest"` (crisp pixels, for pixel art). |
| `size` | `None` | `(width, height)` for raw RGBA pixels. |

[Full reference →](https://albakore.github.io/pyzed/reference/widgets/#image_viewer)

## Related

- [Icon](https://albakore.github.io/pyzed/library/icon/): Lucide icons by name, and SVG images.
- [QR code](https://albakore.github.io/pyzed/library/qr-code/): A QR code for any text or URL.