> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.makeswift.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.makeswift.com/_mcp/server.

# Image

> Adds an Image panel in the Makeswift builder to visually edit an image prop.

Adds an Image panel in the Makeswift builder to visually edit an image prop.

![](/_fern-img/30f7b128602dcf816b2f94bfa248c4bec891c4a445c7cf6765d67a90843d8feb.webp)

The panel has two tabs, so an image can come from either the files manager or an external URL:

* **Files** — Clicking "Choose" or "Replace" opens the Makeswift files manager, where you can upload an image or select an existing one from your media library.
* **URL** — Paste the URL of an image hosted anywhere else.

![](/_fern-img/510d4792b7f5c64b6473c4019693deac48be27396e6292489d16a4807b0f8789.webp)

Your component receives the image URL in both cases, whether the value points at a Makeswift file or an external URL.

> **Warning**
>
> External images don't always carry width and height data. When `format` is set to `Image.Format.WithDimensions` and the external image has no dimensions, your component receives `undefined` and the runtime logs a warning.

## Params

**`label`** `string` — default: Image

Text for the panel label in the Makeswift builder.

---

**`description`** `string`

The description shown in the Panel of the Makeswift builder. This can be written in Markdown format.
Added in [`v0.24.8`](https://github.com/makeswift/makeswift/releases/tag/%40makeswift%2Fruntime%400.24.8).

---

**`format`** `Image.Format.URL | Image.Format.WithDimensions` — default: Image.Format.URL

Changes the prop type this component receives. If set to `Image.Format.URL`, your component receives a `string` value of the image url. If set to `Image.Format.WithDimensions`, your component receives an object of type `ImageWithDimensions`. This format is useful when using components like [`next/image`](https://nextjs.org/docs/pages/api-reference/components/image) that require you to pass the image dimensions as props.

```ts
type ImageWithDimensions = {
  url: string;
  dimensions: {
    width: number;
    height: number;
  };
};
```

---

## Prop type

If `format` is set to `Image.Format.URL`, the prop type is `string`.

If `format` is set to `Image.Format.WithDimensions`, the prop type is `ImageWithDimensions`.

## Example

The following examples adds an Image control to the `icon` prop of a Feature Card component.

### Using `Image.Format.URL`

**`FeatureCard.makeswift.ts`**

```tsx FeatureCard.makeswift.ts
import { Image } from "@makeswift/runtime/controls";

import { runtime } from "@/makeswift/runtime";

import { FeatureCard } from "./FeatureCard";

runtime.registerComponent(FeatureCard, {
  type: "feature-card",
  label: "Feature Card",
  props: {
    icon: ImageControl({
      label: "icon",
      format: Image.Format.URL,
    }),
  },
});
```

**`FeatureCard.tsx`**

```tsx FeatureCard.tsx
interface Props {
  icon?: string;
}

function FeatureCard({ icon = "./default-icon.svg" }: Props) {
  return (
    <div className="p-4 rounded shadow">
      <img src={icon} />
    </div>
  );
}
```

### Using `Image.Format.WithDimensions`

**`FeatureCard.makeswift.ts`**

```tsx FeatureCard.makeswift.ts
import { Image } from "@makeswift/runtime/controls";
import { runtime } from "@/lib/makeswift/runtime";

import { FeatureCard } from "./FeatureCard";

runtime.registerComponent(FeatureCard, {
  type: "feature-card",
  label: "FeatureCard",
  props: {
    icon: Image({
      label: "icon",
      format: Image.Format.WithDimensions,
    }),
  },
});
```

**`FeatureCard.tsx`**

```tsx FeatureCard.tsx
import Image from "next/image";

interface Props {
  icon?: {
    url: string;
    dimensions: {
      width: number;
      height: number;
    };
  };
}

const defaultIcon = {
  url: "/default-icon.png",
  dimensions: {
    width: 100,
    height: 100,
  },
};

function FeatureCard({ icon = defaultIcon }: Props) {
  return (
    <div className="p-4 rounded shadow">
      <Image
        src={icon.url}
        width={icon.dimensions.width}
        height={icon.dimensions.height}
      />
    </div>
  );
}
```

> **Info**
>
> `.makeswift.ts` is a naming convention for organizing Makeswift registration code. [Learn more](/developer/docs/reference/reactruntime/register-component#organizing-registration-code).