# How to build a portfolio showcase in Bubble

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

## TL;DR

Build a filterable portfolio showcase in Bubble with project cards, category tabs, lightbox detail views, and case study pages. This tutorial covers creating the project data structure, designing a responsive grid layout with filtering, building modal popups for project details, and adding dedicated case study pages for in-depth project write-ups.

## Overview: Designing a Portfolio Showcase in Bubble

This tutorial shows you how to build a professional portfolio showcase feature in your Bubble app. You will create a project data structure, design a responsive grid with category filtering, add lightbox popups for quick previews, and build detailed case study pages. Perfect for freelancer platforms, agency websites, or any app where users need to display their work.

## Before you start

- A Bubble account with a new or existing app
- Project images or screenshots ready for upload
- Basic familiarity with Bubble's Design tab and Repeating Groups

## Step-by-step guide

### 1. Create the Project Data Type

Go to the Data tab and create a Data Type called Project. Add fields: Title (text), Description (text), Category (Option Set with values like Web Design, Mobile App, Branding, Photography), Thumbnail (image), Gallery Images (list of images), Client Name (text), Project URL (text), Year (number), Featured (yes/no), and Full Case Study (text). Create the Category Option Set first with your portfolio categories.

**Expected result:** A Project Data Type with all listed fields and a Category Option Set appear in the Data tab.

### 2. Build the portfolio grid with a Repeating Group

Create a page called portfolio. Add a Repeating Group with Type set to Project, Data source: Do a Search for Projects sorted by Year descending. Set the layout to a grid by choosing the number of columns (3 for desktop). In each cell, add an Image element for the Thumbnail filling the cell width, a Text element for the Title, and a smaller Text for the Category. Add a hover overlay effect using a Group with semi-transparent background that appears on the hover conditional.

> Pro tip: Set the Repeating Group to Ext. vertical scrolling for an infinite scroll effect, or use fixed rows with pagination for faster initial load.

**Expected result:** A responsive grid of project cards displays thumbnails, titles, and categories in a clean layout.

### 3. Add category filter tabs above the grid

Above the Repeating Group, add a Row container with button-style Text elements for each category: All, Web Design, Mobile App, Branding, Photography. Create a custom state on the page called Active Category (type: Category Option Set). When a tab is clicked, set Active Category to that category value. For the All tab, set it to empty. Add a conditional on each tab: when Active Category equals this category, change the text color and add an underline. Update the Repeating Group's data source to include a constraint: Category equals Active Category, with Ignore empty constraints checked.

**Expected result:** Clicking a category tab filters the grid to show only projects in that category. The All tab shows everything.

### 4. Create a lightbox popup for project preview

Create a Popup called Popup Project Preview with Type of content set to Project. Inside, add a large Image element for the Thumbnail, Text elements for Title, Description, Client Name, and Year. Add a Gallery section using a Repeating Group (Type: image, source: Parent group's Project's Gallery Images) displayed as a horizontal row of smaller thumbnails. Add a clickable feature: when a gallery thumbnail is clicked, update the main image. Add a View Case Study button that navigates to the case study page, and a Close button.

**Expected result:** Clicking a project card opens a lightbox popup showing the project details and image gallery.

### 5. Build dedicated case study pages

Create a dynamic page called project with Type set to Project. Display the full project details: a hero section with the thumbnail as a banner, Title as h1, Client Name and Year, the full Description, and the complete Gallery Images in a larger grid or slideshow. Below that, display the Full Case Study text field which contains the detailed project write-up. Add navigation links to the previous and next projects for easy browsing.

**Expected result:** Each project has a dedicated page with full details, image gallery, and case study narrative accessible via a clean URL.

## Complete code example

File: `Workflow summary`

```text
PORTFOLIO SHOWCASE — WORKFLOW SUMMARY
======================================

DATA TYPE: Project
  - Title (text)
  - Description (text)
  - Category (Option Set: Web Design, Mobile App, Branding, etc.)
  - Thumbnail (image)
  - Gallery Images (list of images)
  - Client Name (text)
  - Project URL (text)
  - Year (number)
  - Featured (yes/no)
  - Full Case Study (text)

OPTION SET: Category
  - Web Design, Mobile App, Branding, Photography, etc.

PAGE: portfolio
  Custom state: Active Category (Category type)

  Category Tabs (Row container):
    All | Web Design | Mobile App | Branding | Photography
    Click → Set state Active Category = tab's value
    Conditional: Active = this → underline + bold

  Repeating Group (Type: Project, 3 columns)
    Source: Search Projects
      Category = Active Category (Ignore empty)
      Sort: Year descending
    Cell: Thumbnail + Title + Category
    Click → Show Popup Project Preview (display data: cell's Project)

POPUP: Project Preview
  Type: Project
  Elements: Large image, Title, Description, Client, Year
  Gallery: RG (images, horizontal row)
  Buttons: View Case Study → Go to project page | Close

PAGE: project (dynamic, Type: Project)
  Hero: Thumbnail as banner
  Title, Client, Year, Description
  Gallery Grid: RG with Gallery Images
  Full Case Study text
  Nav: Previous/Next project links
```

## Common mistakes

- **Uploading full-resolution images without compression** — Large images cause slow page loads, especially in a grid with many project cards displayed at once Fix: Compress images before uploading and use Bubble's Imgix parameters to serve appropriately sized thumbnails in the grid
- **Not using an Option Set for categories** — Text-based categories lead to inconsistencies like Web Design vs web design that break filtering Fix: Create a Category Option Set and use it for both the Project field and the filter tabs
- **Loading all gallery images in the grid view** — Showing full galleries in each card creates excessive image downloads and slows the page Fix: Show only the Thumbnail in the grid card and load Gallery Images only when the lightbox popup or case study page opens

## Best practices

- Compress images before uploading and use Imgix URL parameters for responsive sizing
- Use Option Sets for project categories to ensure consistent filtering
- Show only thumbnails in the grid and defer full gallery loading to the popup or detail page
- Add lazy loading to the Repeating Group by using pagination or infinite scroll
- Mark featured projects with a badge or larger card size to highlight top work
- Include alt text on all images for accessibility and SEO
- Use dynamic page URLs with the project slug for SEO-friendly case study links

## Frequently asked questions

### How do I make the portfolio grid responsive on mobile?

Set the Repeating Group to show 3 columns on desktop, 2 on tablet, and 1 on mobile using Bubble's responsive breakpoint settings. Adjust the card height at each breakpoint for a clean layout.

### Can I add a search bar to find specific projects?

Yes. Add a Search Input above the grid. Add a constraint to the Repeating Group's data source: Title contains Search Input's value, with Ignore empty constraints checked.

### How do I create a masonry grid layout?

Bubble's Repeating Group uses a uniform grid. For true masonry layout with varying card heights, use a plugin like Masonry Layout or arrange projects into separate column groups manually.

### Can visitors submit their own projects to the portfolio?

Yes. Create a submission form that creates a Project with a Status field set to Pending. An admin reviews and approves submissions by changing Status to Published. Only show Published projects in the portfolio grid.

### Can RapidDev help build a more advanced portfolio platform?

Yes. RapidDev can help you build marketplace-style portfolio platforms with user submissions, client testimonials, analytics on project views, and integrations with Behance or Dribbble APIs.

### How do I add an image carousel in the case study page?

Use a Slideshow plugin from the Bubble marketplace, or build a custom carousel using a Repeating Group showing one image at a time with Previous and Next buttons that change a custom state controlling which image is displayed.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/design-a-portfolio-showcase-feature-in-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/design-a-portfolio-showcase-feature-in-bubble