> From the [Strife developer docs](https://strife.app/docs/reference/field-reference/fields.image). Every page is listed in [llms.txt](https://strife.app/docs/llms.txt).

# fields.image()

Single image upload with required dimension and format hints.

Single image upload. Maps to editor `{ name: 'str-image', type: 'image' }`. Output is the canonical `Image` from `@strifeapp/types`. `width`/`height`/`format` are dimension/transform hints baked into the template — the editor can't override them per asset.

## Example

```ts
fields.image({
  label: 'Cover image',
  localizable: false,
  width: 1600,
  height: 900,
  format: 'webp',
})

fields.image({
  label: 'Logo',
  width: 400,
  height: 'auto',
  format: 'png',
})
```

## Options

| Option         | Type              | Required | Description                                                                                                                        |
| -------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `label`        | `string`          | Yes      | Label shown to editors in Strife Studio.                                                                                          |
| `width`        | `number`          | Yes      | Target width hint used for image transforms.                                                                                      |
| `height`       | `number \| 'auto'` | Yes      | Target height hint, or `'auto'` for a width-only image that keeps the source aspect ratio (crop/zoom are disabled in the editor). |
| `format`       | `ImageFormat`     | Yes      | Target output format — one of `jpeg`, `png`, `webp`, `svg`, `gif`, `avif`, `ico`, `heic`, `tif`, `bmp`.                           |
| `description`  | `string`          | No       | Tooltip shown to editors.                                                                                                          |
| `localizable`  | `boolean`         | No       | When `true`, output is `Record<string, Image>` instead of `Image`.                                                                |
| `searchable`   | `boolean`         | No       | Include in the team's search index.                                                                                               |
| `filterable`   | `boolean`         | No       | Allow filtering content lists by this value.                                                                                      |
| `protected`    | `boolean`         | No       | Restrict editing to users with the appropriate permission.                                                                        |
| `propertyName` | `string`          | No       | Override the stored property name.                                                                                                |
| `paddingColor` | `string \| null`  | No       | Background color used when padding to fit the target dimensions.                                                                  |
| `paddingAlpha` | `number \| null`  | No       | Padding background opacity.                                                                                                       |
| `hideAlt`      | `boolean`         | No       | Hide the alt-text input in the editor.                                                                                            |

> [!NOTE]
> `height: 'auto'` is DSL-only sugar — the compiled template JSON always stores a plain number, with `0` as the width-only convention (`height === 'auto' ? 0 : height`). [Image](https://strife.app/docs/reference/fields/image.md) documents the same `0`-means-width-only convention from the Strife Studio / raw-JSON side.

## Output type

`Image`, or `Record<string, Image>` when `localizable: true`.

## See also

* [Image](https://strife.app/docs/reference/fields/image.md) — the same editor, documented from the Strife Studio UI side.
* [`fields.imageGroup()`](https://strife.app/docs/reference/field-reference/fields.imagegroup.md) — multiple named image slots in one field.