Reference@makeswift/runtimeControls

Image

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

An Image panel with the Files tab selected, showing the selected file and a Replace button

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.
The Makeswift files manager

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

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
stringDefaults to 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.

format
Image.Format.URL | Image.Format.WithDimensionsDefaults to 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 that require you to pass the image dimensions as props.

1type ImageWithDimensions = {
2  url: string;
3  dimensions: {
4    width: number;
5    height: number;
6  };
7};

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

1import { Image } from "@makeswift/runtime/controls";
2
3import { runtime } from "../../../../../makeswift/runtime";
4
5import { FeatureCard } from "./FeatureCard";
6
7runtime.registerComponent(FeatureCard, {
8  type: "feature-card",
9  label: "Feature Card",
10  props: {
11    icon: ImageControl({
12      label: "icon",
13      format: Image.Format.URL,
14    }),
15  },
16});

Using Image.Format.WithDimensions

1import { Image } from "@makeswift/runtime/controls";
2import { runtime } from "../../../../../lib/makeswift/runtime";
3
4import { FeatureCard } from "./FeatureCard";
5
6runtime.registerComponent(FeatureCard, {
7  type: "feature-card",
8  label: "FeatureCard",
9  props: {
10    icon: Image({
11      label: "icon",
12      format: Image.Format.WithDimensions,
13    }),
14  },
15});

.makeswift.ts is a naming convention for organizing Makeswift registration code. Learn more.