Image Widget

The Image widget shows a single image on a page — either from the file archive or from an external URL. Use it to add banners, logos, illustrations, or images that go with content.

When to use this

• You want to add a specific image to a page
• The image should be openable in fullscreen for a closer look
• You want the image to be circular or rounded — for example a profile picture or avatar
• The image comes from an external URL and should be cached in the app

How it works

The widget shows an image you either pick from the Files plugin archive or point to with a URL. You can adjust the image's size, its position on the page, and how it's cropped (circular or rounded). An optional fullscreen toggle lets users open the image in a larger view on click.

Add an image

1. Enable the Files plugin in the applet's Plugin Settings.
2. Open the Design editor for your applet.
3. Add the Image widget to the page.
4. Open the widget settings.
5. Pick Import from — Files or URL.
6. Pick the image or enter the URL.
7. Adjust size, crop, position, and fullscreen as needed.
8. Save your changes.

Widget settings

Source

Setting	Description
Import from	Pick Files to use the file archive or URL for an external address.
Select image	Opens the file picker against the file archive. Shown when the source is Files.
Enter URL	The direct URL of the image. Shown when the source is URL.
Allow caching	When on, the image is stored in the app after the first fetch — faster loading and works offline. Only shown for URL sources.

Size

Setting	Description
Adjust size	Turn on to scale the image.
Size	Percentage 10–100 in steps of 5. The image scales relative to the page width. Shown when Adjust size is on.

Crop

Setting	Description
Circular	Crops the image to a circle — good for avatars and profile pictures.
Rounded	Rounds the corners without cropping to a circle.

TIP

Circular and Rounded cannot be on at the same time. When one is on, the other is locked.

Position

Adjust the image's horizontal placement on the page with the segment control — Left, Center, or Right.

Other

Setting	Description
Allow open in fullscreen	When on, the user can tap the image to open it in a zoomable fullscreen view.

Example

Scenario: You want to put a logo at the top of the home page, centered and at half width, without fullscreen open.

1. Add an Image widget at the top of the home page.
2. Set Import from to Files and pick logo.png from the file archive.
3. Turn on Adjust size and drag the slider to 50%.
4. Set Position to Center.
5. Leave Allow open in fullscreen off — the logo shouldn't be clickable.
6. Save.

Tips

TIP

For profile pictures and avatars, combine Circular with a square source image — that gives you a perfect circle without unwanted cropping.

TIP

Turn on Allow caching for URL images that don't change often. It cuts network requests and makes the app feel faster.

Common mistakes

WARNING

If the image is deleted from the file archive, it won't appear in the widget. Update the widget with a new image when you clean up the file archive.

WARNING

Allow caching only applies to URL sources. Caching for file archive images is handled automatically by AppStudio.