# How to Handle Image Uploads in Bubble

- Tool: Bubble
- Difficulty: Beginner
- Time required: 15-20 min
- Compatibility: All Bubble plans
- Last updated: March 2026

## TL;DR

Image uploads in Bubble use the Picture Uploader or File Uploader elements, which store uploaded images as URLs in your database. You configure accepted file types, add a preview before saving, handle client-side resizing for performance, and store the image URL on a Data Type field. This tutorial covers the complete image upload pipeline from user selection to database storage.

## Overview: Image Uploads in Bubble

This tutorial covers everything you need to know about handling image uploads in Bubble. You will configure the Picture Uploader element, set file type restrictions, add upload preview functionality, store image URLs in your database, and display uploaded images throughout your app. The guide also covers optimization techniques for keeping image sizes manageable.

## Before you start

- A Bubble app with a Data Type that needs image fields
- An image field (type: image) on your target Data Type
- Basic understanding of Bubble elements and workflows

## Step-by-step guide

### 1. Add a Picture Uploader element to your page

In the Design tab, click '+' and search for 'Picture Uploader'. Drag it onto your page. The Picture Uploader is specifically designed for images — it shows a preview of the selected image automatically. Set the 'Dynamic image' to a placeholder or default image. Under 'Accepted file types', you can restrict to specific formats. The element stores the uploaded image URL in its value once the user selects a file.

> Pro tip: Use the Picture Uploader for profile photos and thumbnails where preview matters. Use the File Uploader for general file uploads where you also accept non-image files.

**Expected result:** A Picture Uploader element appears on the page ready to accept image selections with automatic preview.

### 2. Configure accepted file types and size limits

In the Picture Uploader's properties, you can set accepted file types by listing MIME types or extensions. Common image types: .jpg, .jpeg, .png, .webp, .gif. To enforce a file size limit, Bubble does not have a built-in max size setting on the element, so add a conditional on your Save button: 'Only when Picture Uploader's value's file size is less than 5000000' (5MB in bytes). Show an error message when the condition is not met.

**Expected result:** The uploader only accepts specified image formats, and the save workflow is blocked for files exceeding the size limit.

### 3. Preview the image before saving

The Picture Uploader automatically shows a preview of the selected image within the element itself. For a larger preview, add a separate Image element on the page. Set its dynamic source to 'Picture Uploader's value'. This displays a full-size preview as soon as the user selects a file. You can also add conditional formatting — when 'Picture Uploader's value is empty', show a placeholder text like 'No image selected'.

**Expected result:** Users see a preview of their selected image before committing to save it to the database.

### 4. Save the uploaded image to the database

Create a workflow on your Save button. Add a 'Create a new Thing' or 'Make changes to a Thing' action. For the image field, set it to 'Picture Uploader's value'. Bubble automatically hosts the image on its servers and stores the URL. After saving, reset the Picture Uploader with the 'Reset data' action to clear the selection. If you are updating an existing record (like a profile photo), use 'Make changes to Current User' and set the profile_image field.

**Expected result:** The uploaded image URL is stored in the database field, and the uploader resets for a new selection.

### 5. Display uploaded images throughout your app

To display a stored image, add an Image element and set its dynamic source to the data field (e.g., 'Current User's profile_image' or 'Current cell's Product's main_image'). Bubble automatically serves images through Imgix, which provides on-the-fly resizing. Append URL parameters to optimize delivery: add '?w=200&h=200&fit=crop' to the image URL for thumbnails. In Repeating Groups, each cell's image element references 'Current cell's [Type]'s [image field]'.

> Pro tip: Bubble's Imgix integration means you can request specific sizes without uploading multiple versions. Just modify the URL parameters for different display contexts.

**Expected result:** Uploaded images display throughout the app with automatic optimization via Bubble's image CDN.

### 6. Handle multiple image uploads

For multiple images (like a product gallery), use a list of images field on your Data Type. Add a File Uploader element (not Picture Uploader) with the 'Allow multiple files' option checked. In the save workflow, set the list of images field to 'FileUploader's value' (which returns a list of file URLs). To display them, use a Repeating Group with type 'image' and data source set to the list field. Each cell contains an Image element showing 'Current cell's image'.

**Expected result:** Users can upload multiple images at once, stored as a list, and displayed in a gallery-style Repeating Group.

## Complete code example

File: `Workflow summary`

```text
IMAGE UPLOAD — WORKFLOW SUMMARY
=================================

ELEMENTS:
  Picture Uploader: single image with preview
  File Uploader: multiple files, allow multiple = yes
  Image element: display stored images

SINGLE IMAGE UPLOAD WORKFLOW:
  Event: Button Save is clicked
  Condition: Picture Uploader's value is not empty
    AND file size < 5000000 (5MB)
  Step 1: Create/Make changes to Thing
    image_field = Picture Uploader's value
  Step 2: Reset data → Picture Uploader

MULTIPLE IMAGE UPLOAD:
  FileUploader: allow multiple files = yes
  Workflow: Set list_of_images = FileUploader's value

DISPLAYING IMAGES:
  Single: Image element → source = Thing's image_field
  Gallery: Repeating Group (type: image)
    source = Thing's list_of_images
    Cell: Image → Current cell's image

IMGIX OPTIMIZATION:
  Thumbnail: image_url?w=200&h=200&fit=crop
  Medium: image_url?w=600&h=400&fit=max
  Full: image_url (no parameters)

FILE TYPE RESTRICTIONS:
  Accepted: .jpg, .jpeg, .png, .webp, .gif
  Size limit: conditional on save button
```

## Common mistakes

- **Using a File Uploader instead of Picture Uploader for profile photos** — The File Uploader does not show an image preview — users cannot see what they selected before saving Fix: Use the Picture Uploader element for single image uploads where visual preview is important
- **Not restricting accepted file types** — Users can upload non-image files (PDFs, ZIPs) into image fields, which will not display properly Fix: Set accepted file types to .jpg, .jpeg, .png, .webp, .gif on the uploader element
- **Allowing unlimited file sizes without validation** — Very large images (10MB+) slow down page loads and consume excessive storage on your Bubble plan Fix: Add a file size check condition on your save button and show an error for oversized files

## Best practices

- Use Picture Uploader for single images with preview, File Uploader for multiple files
- Restrict accepted file types to common image formats (.jpg, .png, .webp)
- Add file size validation before saving — 5MB is a reasonable limit for most use cases
- Use Bubble's Imgix URL parameters (?w=200&h=200) for optimized thumbnail delivery
- Reset the uploader after saving to provide a clear UI state
- Store images as the 'image' field type (not 'file' or 'text') for proper CDN optimization
- Consider a 'processing' state while large images upload to prevent users from clicking save too early

## Frequently asked questions

### What is the maximum file size Bubble allows for uploads?

Bubble allows uploads up to 50MB per file by default. However, for images, you should enforce a much lower limit (2-5MB) for performance.

### Where are uploaded images stored?

Bubble stores uploaded files on Amazon S3 and serves them through Imgix CDN. The URL is stored in your database field.

### Can I crop images before uploading in Bubble?

Bubble does not have a built-in crop tool. Use a plugin like 'Image Cropper' from the marketplace, or use Imgix URL parameters for server-side cropping after upload.

### How do I delete uploaded images that are no longer used?

Bubble does not automatically clean up orphaned files. When you remove an image reference from a record, the file remains on Bubble's servers. The File Manager in the Data tab lets you manually delete files.

### Can RapidDev help build a complete image management system in Bubble?

Yes. RapidDev can build image upload systems with cropping, compression, gallery displays, and CDN optimization for your Bubble app.

### Can users upload images from their phone camera directly?

Yes. On mobile browsers, the Picture Uploader and File Uploader both trigger the device's camera/gallery picker, allowing direct camera capture.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/handle-image-uploads-in-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/handle-image-uploads-in-bubble