The Image block displays a single picture sourced from a URL or an uploaded file (SVG, PNG, JPG, JPEG, WEBP). Control how it fills its box with Image Fitting, give it Alt Text, add a hover Tooltip, fall back to a custom layout when the picture fails, and open it full-screen via a method.
Image — Content Properties
Property | Type | Default | Appears When | Description |
|---|---|---|---|---|
Image Source | URL or Upload | URL | Always | Where the picture comes from |
Image URL | string (bindable) | placeholder gradient | Image Source = URL | The image web address. Supports expressions and bindings |
Upload | uploaded file (max 1) | — | Image Source = Upload | SVG, PNG, JPG, JPEG, or WEBP only |
Alt Text | string (translatable) | — | Always | Alt text for accessibility and load failures |
Slots → Fallback | block slot | empty | Always | Custom layout shown when the image fails to load |
Add-ons → Tooltip (text) | string | — | Always | Tooltip text shown on hover. The tooltip only renders when this has a value |
Add-ons → Tooltip (placement) | placement | top | Tooltip text set | Where the tooltip opens |
Interactions | event list | — | Always | On Click event handler |
Permissions | permission rules | — | Always | Restrict who sees the block |
Image Fitting Options
| Label | CSS Value | Behavior |
| Fill & Crop (default) | object-cover | Fills the box, cropping overflow. Default for new blocks |
| Scale but Preserve Image | object-contain | Scales to fit fully inside; may leave empty space |
| Stretch to Fill | object-fill | Stretches to fill exactly, distorting proportions |
| Original Size | object-none | Keeps native pixel size; crops if larger than box |
| Smart Fit | object-scale-down | Uses whichever of contain or original is smaller |
Image Methods
| Method | Description | Platform |
| Open In Media Viewer | Opens the current image full-screen in a zoomable viewer with a close button | Web only |
Image — Exposed State
| Binding | Type | Description |
{{ id.content.data.src }} | string | The configured image URL (after bindings resolve) |
{{ id.content.data.alt }} | string | The configured alt text |
{{ id.appearance.objectFit }} | string | The active fitting mode |
{{ id.state.isOpenInMediaViewer }} | boolean | Whether the full-screen media viewer is currently open |
Image Behaviors & Gotchas
Note: Broken image shows your fallback slot, or a built-in placeholder: When the picture fails to load, the block swaps in the Fallback slot. If empty, a built-in gradient placeholder appears — not a broken-image icon.
Note: Fill & Crop crops by default: New blocks default to object-cover, which fills the box and cuts off overflow. Switch to "Scale but Preserve Image" to show the whole picture.
Warning: Full-screen viewing is opt-in and web-only: To get lightbox behavior, add an On Click interaction that runs this block's Open In Media Viewer method. Mobile apps don't offer this method.
Note: Uploads capped at one image and five file types: SVG, PNG, JPG, JPEG, WEBP only. Drop a second file and it replaces the first.
Avatar Block
The Avatar block shows a circular representation of a person or entity in three display modes: derived Initials, an Icon, or an Image (URL or uploaded). Two add-ons extend it: a Label (name + caption beside the circle) and a Badge (a status dot or text pinned to the circle). New blocks arrive pre-bound to the signed-in user.
Avatar — Content Properties
Property | Type | Default | Description |
|---|---|---|---|
Display as | Initials, Icon or Image | Initials | What the circle displays |
Icon | icon | — | Icon shown inside the circle. Appears when Display as = Icon |
Image Source / Image URL | URL or Upload (SVG, PNG, JPG, JPEG, WEBP) | URL | Image source. Appears when Display as = Image |
Name | string (bindable, translatable) | signed-in user's username | The full name the avatar represents. The initials come from it, and it is the fallback when an image fails to load |
Initials | M or MJ | M | How many letters the initials show. MJ takes the first letter of the first and last words |
Add-ons → Label | Label, Caption, position, alignment, typography | on for new blocks | Name and caption text beside the circle, with position (left, right, top, bottom) and alignment controls |
Add-ons → Badge | Size (Small, Medium, Large), Color (Error, Success, Warning, Info), Type (Text or Dot), Text | off | Status badge pinned to the circle. Text shows a short value; Dot shows a colored dot |
Interactions | event list | — | On Click event handler |
Permissions | permission rules | — | Restrict who sees the block |
Avatar — Appearance Properties
Property | Type | Default | Description |
|---|---|---|---|
Size | xxs, xs, sm, md, lg, xl, 2xl (20 to 64 px) | sm | Diameter of the circle |
Background Color | theme swatch (conditions allowed) | brand | Fill of the circle. Add a condition to change it with your data |
Icon Color | theme text color | — | Color of the icon inside the circle. Appears only when Display as = Icon and an icon is chosen |
Border → Stroke | width and color | none | Border around the circle |
Visibility | conditions | visible | Show or hide the block |
Styles | Width, Height, Flex Layout, Margin, Padding, Gap, Rotation | fit to content | Box styling for the whole block |
Avatar — Events, Methods and Exposed State
Events: On Click only. With the Label add-on on, the whole row (circle, label and caption) is the click target; without it, only the circle.
Methods: none.
Exposed state: the configured content, for example
{{ id.content.fallbackText }}(the Name) and{{ id.content.type }}(the display mode). The rendered initials aren't exposed.
Note: A Text badge with empty text shows nothing. Give it text or switch its Type to Dot. The Info badge color renders gray.
Avatar Example: Record Owner with a Status Badge
Add an Avatar block and keep Display as set to Initials.
Bind Name to the owner's name from your data source, for example
{{ ds_ticket.data.ownerName }}. The path depends on your data source's response.Under Add-ons → Label, bind Label to the same name and Caption to the owner's role or team.
Turn on Add-ons → Badge, set Type to Dot and Color to Success to show the owner as available.
Optional: in Appearance, add a condition to Background Color so the circle changes color with the record's status.
Avatar Group Block
The Avatar Group block renders a row of overlapping avatars representing several people — use it instead of multiple individual Avatar blocks when showing a team or assignee list. Key differences from the single Avatar block:
Type: Mapped (avatars built from a data array) or Static (avatars you add one by one under Avatars)
Each avatar has a label and displays as initials, an icon or an image (URL or upload)
Max visible avatars (default 3): extra avatars collapse into a "+N" chip
Size and Initials (M or MJ) apply to every avatar in the group
The overlap is fixed by the size; change it only with custom styles
Icon Block
The Icon block renders a small vector glyph from the icon set. Use it for decorative UI symbols — arrows, check marks, status indicators — rather than photographs or complex images. It supports size, color, a Variant (Default or Fill) and Tooltip and Badge add-ons. A new Icon block shows the Plus icon. Icon is display-only: to make a glyph clickable, use Icon Button or wrap it in a Pressable.
Icon — Key Properties
Property | Type | Description |
|---|---|---|
icon | icon name (conditional) | The icon to display. Supports conditional values so the icon can change based on state. New blocks start with the Plus icon |
variant | Default | Fill | The icon's visual style |
size | xs | sm | md | lg | xl | The icon's rendered size |
color | theme color token or custom | The icon's fill/stroke color |
Add-ons → Tooltip | add-on | Tooltip shown on hover |
Add-ons → Badge | add-on | Badge pinned to the icon |
interactions | event list | Legacy, read-only. Shown only on older Icon blocks that already have an On Click handler; you can't add one to a new Icon block |
visibility | conditions | Show/hide the block |
permissions | permission rule | Restrict who sees the block |
Icon Button Block
The Icon Button block is a clickable icon-only button — an Icon with button affordances (hover state, keyboard activation, click event, disabled state, tooltip). Use when you want an icon that triggers an action but has no visible text label.
Icon Button — Key Properties
Property | Type | Description |
|---|---|---|
icon | icon name (conditional) | The icon to display |
variant | solid | outline | soft | ghost | The button's visual style |
color | brand | neutral | success | danger | The button's color scheme |
size | xs | sm | md | lg | The button's size |
disabled | condition | Disables the button — no click event fires when disabled |
Add-ons → Tooltip (Text or Custom) | add-on | Tooltip shown on hover (important for accessibility with icon-only buttons). See Icon Button & Link for the Text and Custom types |
interactions | event list | On Click event handler. On Long Press is also available on mobile and tablet |
loading | boolean | condition | Shows a loading spinner in place of the icon while true |
permissions | permission rule | Restrict who sees the button |
See Icon Button & Link for the full Icon Button reference.
Note: Always set a Tooltip for icon-only buttons: Without visible text, a tooltip is the only way assistive technology and unfamiliar users can understand what the button does.
Which Block to Use
| You want to… | Use |
| Display a single photo, banner, or illustration | Image |
| Show a user profile picture with initials fallback | Avatar |
| Show multiple overlapping user avatars | Avatar Group |
| Display a UI glyph/symbol (decorative, not clickable) | Icon |
| Create an icon that triggers an action on click | Icon Button |
| Show many images in a grid or gallery | Image Grid |
| Display video, audio, or mixed file types | Media |
| Create a swipeable set of image slides | Carousel |
| Make an arbitrary area clickable (not just an image) | Pressable |