Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

import { Property, PropertyList, ExpandableSection } from "@wix/docs-ui/content";

# Image

An image from Wix Media, carried at runtime as an object with the URL to render along with
its dimensions, crop, and accessibility text. Use it for any field that shows a picture the
user picks from the Media Manager, such as a hero image or a product photo.

## Component

In your component code, import the `Image` type from `@wix/editor-react-types`:

```ts
import type { Image } from '@wix/editor-react-types';
```

An `Image` has the following properties:

<PropertyList bordered>
  <Property
    name="url"
    type="string"
    required
    description="The fully resolved image URL. Render this."
  />
  <Property name="uri" type="string">
    The Wix Media URI, such as `'wix:image://v1/abc123.jpg'`.
  </Property>
  <Property
    name="name"
    type="string"
    description="The image file name."
  />
  <Property
    name="height"
    type="number"
    description="The image height in pixels."
  />
  <Property
    name="width"
    type="number"
    description="The image width in pixels."
  />
  <Property
    name="animated"
    type="boolean"
    description="Whether the image is animated, such as a GIF."
  />
  <Property
    name="crop"
    type="{ x, y, width, height }"
    description="The crop region applied to the image, all in pixels."
  />
  <Property
    name="quality"
    type="number"
    description="The image quality, as a percentage from 0 to 100."
  />
  <Property
    name="alt"
    type="string"
    description="The image alt text for accessibility."
  />
</PropertyList>

### Usage

Your code either consumes a value of type `Image` or produces one:

::::tabs
:::Consumers
In a component that receives an `Image`, apply its fields to an image element:

```tsx
import type { Image } from '@wix/editor-react-types';

function Hero({ heroImage }: { heroImage?: Image }) {
  return (
    <img
      src={heroImage?.url}
      width={heroImage?.width}
      height={heroImage?.height}
      alt={heroImage?.alt}
    />
  );
}
```
:::
:::Producers
When your code produces an `Image`, for a context or a function return, set `url` for
the consumer to render, along with the dimensions and alt text:

```ts
import type { Image } from '@wix/editor-react-types';

const heroImage: Image = {
  uri: 'wix:image://v1/hero123.jpg',
  url: 'https://static.wixstatic.com/media/hero123.jpg',
  name: 'hero-image.jpg',
  width: 1920,
  height: 1080,
  quality: 90,
  alt: 'Handmade ceramic mug on a wooden table',
};
```
:::
::::

## Manifest

In your manifest, declare the field with the `image` dataType:

```json
{ "dataType": "image" }
```

### Declaration

Declare an `image` field in one of these ways, depending on where the value comes from:

::::tabs
:::Data-property
Declare it as a data property when the Wix user should pick the `heroImage` in a panel. It
takes `dataType`, `displayName`, an optional `defaultValue`, and the options that follow:

```json
{
  "heroImage": {
    "dataType": "image",
    "displayName": "Hero Image",
    "defaultValue": {
      "uri": "wix:image://v1/hero123.jpg",
      "width": 1920,
      "height": 1080,
      "quality": 90,
      "alt": "Handmade ceramic mug on a wooden table"
    },
    "image": {
      "category": "IMAGE"
    }
  }
}
```

> **Your `defaultValue` sets a media reference, not the full object.** It provides a `uri`
> that points to an item in Wix Media. Before your component runs, the editor resolves that
> `uri` into the complete `Image` object it receives, including the `url`. Do not set `url`
> in your manifest.

#### Options

An `image` data property accepts the following options:

<PropertyList bordered>
  <Property
    name="category"
    type="string"
    description="Sets which Media Manager category the user picks the image from. Omit it to leave the category unspecified."
  >
    <ExpandableSection name="category values">
      <PropertyList>
        <Property name="'IMAGE'" description="General images." />
        <Property name="'IMAGE_BACKGROUND'" description="Background images." />
      </PropertyList>
    </ExpandableSection>
  </Property>
</PropertyList>
:::
:::Context-item
Declare it as a context item when your component supplies the image to descendant
components. It takes just `dataType` and `displayName`:

```json
{
  "heroImage": {
    "dataType": "image",
    "displayName": "Hero Image"
  }
}
```
:::
:::Function-parameter-and-return
Declare it on a function when the function accepts or returns an image. It takes
`dataType` and an optional `displayName`, and a parameter may also set `optional`:

```json
{
  "parameters": [
    {
      "dataType": "image",
      "displayName": "Hero Image"
    }
  ],
  "returns": {
    "dataType": "image"
  }
}
```
:::
::::