Skip to main content
Version: Next

Image

The <image> element is used for embedding images into the UI.

Image size​

To add an image to a block, you’ll use the <image> tag and set the imageHeight and imageWidth attributes. These fields specify the preferred size of the image in pixels (usually this is the size of the file you uploaded). The imageHeight and imageWidth attributes are required when adding an image.

In this example, imageHeight and imageWidth are set to 250 pixels, and the block size is not specified.

<blocks>
  <image
    url="fuzzyFingers.png"
    imageWidth={250}
    imageHeight={250}
    description="Generative artwork: Fuzzy Fingers"
  />
</blocks>

app_image_fixed_size

Block size​

You can also set the block size that holds the image using the height and width parameters to set the maximum percentage of the block’s size relative to the parent.

When you set the block size, the same 250 pixel imageHeight and imageWidth fields specify the resolution and aspect ratio of the image itself and no longer only the size. Notice the image renders differently than when you didn’t set the block size above.

<blocks>
  <image
    url="fuzzyFingers.png"
    height="75%"
    width="75%"
    imageWidth={250}
    imageHeight={250}
    resizeMode="fit"
    description="Generative artwork: Fuzzy Fingers"
  />
</blocks>

app_image_relative_size

Attributes​

url​

A string pointing to an image resource. Possible values:

  • Local file
    • spinner.gif
    • For referencing local files in the /assets folder
  • URL
    • Only works for reddit hosted domains
    • https://www.redditstatic.com/desktop2x/img/id-cards/[email protected]
  • SVG String
    • data:image/svg+xml, <svg>...</svg>

Examples​

A local image that resizes to cover its entire area

<image
  imageHeight={1024}
  imageWidth={1500}
  height="100%"
  width="100%"
  url="background.png"
  description="striped blue background"
  resizeMode="cover"
/>

SVG template literal

<image
  imageWidth={400}
  imageHeight={300}
  width="200px"
  height="150px"
  url={`data:image/svg+xml,
    <svg
      width="400"
      height="300"
      viewBox="0 0 400 300"
      xmlns="http://www.w3.org/2000/svg"
    >
      <rect x="50" y="50" width="300" height="200" fill="red" />
    </svg>
  `}
/>

imageHeight​

A number representing the intrinsic image height.

imageWidth​

A number representing the intrinsic image width.

width​

A string that sets a width of the block. Possible values:

  • Absolute: 100px
  • Relative: 50% (The default if the unit is not specified, i.e. width="50")

A block's width will be omitted if the relative width is invalid and the parent is a hstack. If the parent is a zstack, then an invalid width will always be omitted.

A relative width is valid if it meets one of the following rules:

  • Parent block must have a defined width or infer its width from an ancestor.
  • Parent block must stretch horizontally in a vstack (see alignment).
  • Parent block must grow horizontally in a hstack.
note

Relative width can only grow or stretch in a constrained dimension. The nearest ancestor without a definition will break the chain, and the block's width will be omitted.

Relative (Percent) Examples

Valid dimensions

<hstack backgroundColor="red" width="200px" height="200px">
  <zstack height="100%" width="100%" backgroundColor="green" />
</hstack>

Z stack dimensions are valid because it satisfies the following rules:

  • Height: Parent block must have the height defined.

  • Width: Parent block must have the width defined.

<vstack backgroundColor="yellow" width="300px" height="300px">
  <hstack backgroundColor="red" height="200px">
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

Z stack dimensions are valid because it satisfies the following rules:

  • Height: Parent block must have the height defined.

  • Width: Parent block must be stretching horizontally in a vstack. The parent hstack is stretching horizontally in the vstack, because the vstack does not have any alignment indicated on the cross axis. (See alignment)

<vstack backgroundColor="yellow" width="300px" height="300px">
  <hstack backgroundColor="red" width="200px" grow>
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

Z stack dimensions are valid because it satisfies the following rules:

  • Height: Parent block must be growing vertically in a vstack. The parent hstack is growing vertically along the main axis of the vstack because it has grow indicated. (See grow)

  • Width: Parent block must have the width defined.

Invalid dimensions

<vstack backgroundColor="yellow" width="300px" height="300px" alignment="start top">
  <hstack backgroundColor="red">
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

Z stack dimensions are invalid because it does not satisfy any of the rules:

  • Height: hstack is not growing vertically because it does not indicate grow. Therefore, there is no parent height for the zstack to base its height=100% on.
  • Width: hstack is not stretching horizontally because because the vstack indicates an alignment. Therefore, there is no parent width for the zstack to based its width=100% on. Width will be omitted, because the relative width is invalid and the parent is an hstack.

Inferred dimensions

<vstack backgroundColor="yellow" width="300px" height="300px">
  <hstack backgroundColor="red" width="200px" grow>
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

In this example, the hstack infers its height definition from the vstack (height = 300px), so the zstack dimensions are valid.

<vstack backgroundColor="yellow" height="300px">
  <hstack backgroundColor="red" height="200px">
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

In this example, the vstack does not specify width, so there’s nothing for the hstack to infer. The width of the zstack is invalid. Therefore, the width will be omitted.

minWidth​

Prevents the used value of width from becoming smaller than the minimum width if set.

maxWidth​

Prevents the used value of width from becoming larger than the maximum width if set.

height​

A string that sets a height of the block. Possible values:

  • Absolute: 100px
  • Relative: 50% (The default if the unit is not specified, i.e. height="50")

A block's height will be omitted if the relative height is invalid and the parent is a vstack. If the parent is a zstack, then an invalid height will always be omitted.

A relative height is valid if it meets one of the following rules:

  • Parent block must have a defined height or infer its height from an ancestor.
  • Parent block must stretch vertically in a hstack (see alignment).
  • Parent block must grow vertically in a vstack.
note

Relative height can only grow or stretch in a constrained dimension. The nearest ancestor without a definition will break the chain, and the block's height will be omitted.

Relative (Percent) Examples

Valid dimensions

<hstack backgroundColor="red" width="200px" height="200px">
  <zstack height="100%" width="100%" backgroundColor="green" />
</hstack>

Z stack dimensions are valid because it satisfies the following rules:

  • Height: Parent block must have the height defined.

  • Width: Parent block must have the width defined.

<vstack backgroundColor="yellow" width="300px" height="300px">
  <hstack backgroundColor="red" height="200px">
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

Z stack dimensions are valid because it satisfies the following rules:

  • Height: Parent block must have the height defined.

  • Width: Parent block must be stretching horizontally in a vstack. The parent hstack is stretching horizontally in the vstack, because the vstack does not have any alignment indicated on the cross axis. (See alignment)

<vstack backgroundColor="yellow" width="300px" height="300px">
  <hstack backgroundColor="red" width="200px" grow>
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

Z stack dimensions are valid because it satisfies the following rules:

  • Height: Parent block must be growing vertically in a vstack. The parent hstack is growing vertically along the main axis of the vstack because it has grow indicated. (See grow)

  • Width: Parent block must have the width defined.

Invalid dimensions

<vstack backgroundColor="yellow" width="300px" height="300px" alignment="start top">
  <hstack backgroundColor="red">
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

Z stack dimensions are invalid because it does not satisfy any of the rules:

  • Height: hstack is not growing vertically because it does not indicate grow. Therefore, there is no parent height for the zstack to base its height=100% on.
  • Width: hstack is not stretching horizontally because because the vstack indicates an alignment. Therefore, there is no parent width for the zstack to based its width=100% on. Width will be omitted, because the relative width is invalid and the parent is an hstack.

Inferred dimensions

<vstack backgroundColor="yellow" width="300px" height="300px">
  <hstack backgroundColor="red" width="200px" grow>
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

In this example, the hstack infers its height definition from the vstack (height = 300px), so the zstack dimensions are valid.

<vstack backgroundColor="yellow" height="300px">
  <hstack backgroundColor="red" height="200px">
    <zstack height="100%" width="100%" backgroundColor="green" />
  </hstack>
</vstack>

In this example, the vstack does not specify width, so there’s nothing for the hstack to infer. The width of the zstack is invalid. Therefore, the width will be omitted.

minHeight​

Prevents the used value of height from becoming smaller than the minimum height if set.

maxHeight​

Prevents the used value of height from becoming larger than the maximum height if set.

description​

A string for describing an image. Helpful for improving accessibility, as it's used by screen readers to read the attribute value out to users so they know what the image means.

resizeMode​

An enum specify how to display the image in the block. Possible values:

  • fit (default) resizes the image to fit the container and maintain aspect ratio.

app_image_fit

  • fill resizes the image to fill the container but may lose aspect ratio.

app_image_fill

  • cover scales the image to fit the entire container and maintain aspect ratio. The image may be cropped based on the container size.

app_image_cover

  • scale-down resizes the image to the smallest fit and maintains the aspect ratio.

grow​

A boolean that allows the block to expand to fill all available space along the axis of its parent container if set to true. Possible values:

  • true
  • false: The default if the attribute is not used.

Has no effect inside a <zstack>.

Functions​

onPress​

Attaches an event handler for press events on the block.

Examples​

<image onPress={() => console.log('world')}>Hello</image>

Notes​

Examples​

A button that increments a counter

import { Devvit, useState } from '@devvit/public-api';

Devvit.addCustomPostType({
  name: 'Say Hello',
  render: (context) => {
    const [votes, setCounter] = useState(0);
    return (
      <blocks>
        <vstack alignment="center middle" height="100%" width="100%">
          <button icon="upvote-outline" onPress={() => setCounter(votes + 1)}>
            {votes}
          </button>
        </vstack>
      </blocks>
    );
  },
});

Example​

Something you might run into when adding assets is that the images could be large enough to push some content outside of the visible frame. If you notice that happening, you can adjust the container height and image width using height, grow, and resizeMode. See the following example:

<blocks height="tall">
  <vstack gap="medium" padding="medium" height={100}>
    <text>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut sed malesuada tortor. Phasellus
      velit eros, fermentum vitae cursus ut, condimentum nec tellus.
    </text>
    ​
    <image url="asset.png" imageWidth={123} imageHeight={123} grow width={100} resizeMode="fit" />​
    {/* Footer */}
    <hstack gap="medium">
      <button grow>Option 1</button>
      <button grow>Option 2</button>
    </hstack>
  </vstack>
</blocks>