Components
/
Image

Image

Display an image to users. The image component displays a single image that can dynamically change based on user interaction. Often, these are product photos, user headshots, or user-submitted visual content.

Ways to use an image

In-line within other components

You can add an in-line image (child component) to a table, detail view, or card list (parent component). The image is automatically displayed for every record in the parent component and is usually bound to data from that record.

Example:
You have a table showing a list of potential Scooters that need to be approved. You can add an image that corresponds to the scooter in that row (the image name for each scooter is within the data of that row).

Image browser bound to a table

A single image component can display different images based on the row a user selects in a table, letting you create a simple image browsing tool.

Example:
You have a table showing a list of potential Sample Images. Next to it, you have an image component that’s bound to the filepath field in the table, which has the image filename. Selecting a row in the table will now display the image next to it.

Display private images in your S3 bucket

If you've added a S3 data source you can use the image component's advanced features to display non-publicly available images (we'll sign using your S3 credentials).

Configuring your image

Source & Image URL

The image displayed is based on a template URL that you define. This template specifies the path (and filename) for your image.

Example template:
https://assets.example-files.com/${customField1.value}


In this example, we have a fixed portion of the URL: https://assets.example-files.com/ as well as the variable portion ${customField1.value}.
The variable portion will pull the remainder of the path (including the image filename) from what is entered into the filter component (named customField1).

Thus, if what was entered into customField1 was image1.jpg, the image component would display the image at https://assets.example-files.com/image1.jpg. This image will change when a user inputs something different into customField1.

First, you'll need to decide how you're going to construct the template URL:

1 - Use data from parent component (for in-line images) or from another component in this Space

If you have existing components in the Space that contains the data needed for the URL, you don’t need to grab additional data from your source, and you can keep the “This image does not require a source” checkbox checked. You should also keep this box checked if the image is in-line within a parent component, and you want to use data in the parent component. 

Begin constructing your template URL, and then click “Insert a variable”. Specify the component and then the field that you want to use in your template URL. If you’re working with an in-line image, you can reference the parent component’s data ("This Row"/"This Table"/etc).


Parent Component Example:
Let’s walk through our in-line images in a Scooters table from the first example. Each scooter has an associated image, with the filename contained in a field called Image Name. You can insert an image in-line, and specify that the URL is completed with the filename coming from the Image Name field.

Existing (non-parent) Component Example:
Let's walk through our second example from above, showing a "Sample Images" table with an image component next to it. Your sample images are stored at the path https://picsum.photos/. Each image file name is stored in the "Samples" database table, under the column filepath (ie, "401.jpg").

When you go to configure your image component, in template, enter https://picsum.photos/ and then click "Insert a variable”. Choose the “Samples” table you added earlier, and then choose Selected Row -> Data -> filepath.

2 - Fetch data from source

If there are no existing components with the data you want to use, you can use a function to fetch data from your data source. Uncheck the checkbox, then choose the data source and then the data you want to use. 

Next, you'll build out the template URL as before - starting with the fixed path, and then using the "insert a variable" link. This time, you'll want to select This Image -> Data -> columnname, where columnname contains the variable data you need for the image URL.



Example without requiring a source:
Let's use the same set-up as the previous example, where we have a table "Samples" that has a column filepath with the data we need for the image URL.

This time, we're unchecking the checkbox and then selecting our data source (“Test Images” database) and then the function to retrieve data from our Samples table. Then we fill out the fixed part of the URl template, and add a variable. We select This Image (referring back to this component), and then the filepath field we need.

Filters & Sorting

If you fetch directly from a source, you'll need to specify which record's data to use. For example, if you chose to use the filepath field, you still need to specify which record's filepath should be used (i.e., which row of table data).

You can do this by setting filters to identify a specific record. If more than one record fulfills the filter criteria, the first available record's data will be used for this image. Ordering criteria (see below) can help you influence what record is first.

Go to the "Filters" section and click “+” to add your first filter.

Each filter has a data field which is compared to a value. A preset filter compares against a fixed value, whereas a dynamic filter compares against data from another component.

Dynamic filter example

Let's say you want to display the headshot of a user, if their ID is entered into a filter component called userID. We also have a database table called Headshots, which has an ID for each user and a filepath column with that user's headshot's filename.

We'll add and configure an image to fetch the filepath data from the Headshots table in our data source. We then add our dynamic filter in our image configuration, specifying that we should grab the data from the record whose ID matches the userID filter value.

Preset filter and ordering example

Less commonly, you may want to compare against a fixed value. Usually using a fixed value will get you the same image (until the underlying data changes), but we can also use the sort to influence what image appears. Let's use our previous example, but this time we want to display the headshot of the most recent active user. In your Headshots database table, you also have the status of each user ("active"/"suspended") as well as the last_login date/time.

We can create a filter to only show "active" status, and then sort the records by last_login in descending order - this will mean that the active user who most recently logged in will be the record this image component binds to (and will show that user's headshot).

Sign your image

To allow the download and display of images from a private S3 bucket, you can sign the request with your S3 credentials. Simply select the S3 data source.

Text

Name your image component (used to reference this component in Internal). You can also add an image title that will appear above the image.


Visibility Rules

You can create visibility rules that will determine when this component is visible and able to be interacted with.

Design

Left and Top options only appear for top-level components (components that are placed directly onto the Space canvas).

Left: Set the distance of this component from the left edge of the Space canvas (x-axis position). This can be expressed as a % of the canvas or as a number of pixels.

Top: Set the distance of this component from the top edge of the Space canvas (y-axis position). This can be expressed as a % of the canvas or as a number of pixels.

Width: Set the width of this component as a number of pixels or as a % of the containing unit.

Height: Set the height of this component as a number of pixels or as a % of the containing unit.

If the component is a top-level component, the containing unit is the Space canvas.

If the component is in-line within another component, the containing unit is the parent component.

If the component is within a flexbox component, the containing unit is the flexbox.

Snap to Grid: Set the edges of this component to snap to the grid canvas in the Space.