> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/experience-cloud/experience-components/ax-gallery.md).

# AX - Gallery

## Overview

**AX - Gallery** is an Experience Cloud component that displays images and content in four layout styles on Experience Sites pages: carousel (slideshow), tabs (organized sections), grid (multi-column), or gallery (image showcase).

Use it to display product photos, project portfolios, case study images, resource collections, or any visual content that portal users need to browse. Configure the layout style, navigation, and image sources in Experience Builder without code.

<figure><img src="https://2929066058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDL6JQuZArjJeQvX2ot4y%2Fuploads%2Fgit-blob-78fd9148b4aaecf3a5c1b61a0bdf7f0664ad4347%2F2024-02-07_21-13-18%20(1).gif?alt=media" alt=""><figcaption></figcaption></figure>

## Tutorials

Follow these step-by-step guides to build with this component.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="https://docs.avonnicomponents.com/projects/use-cases/portals-and-partner-sites/fall-course-catalog.md">Build a Salesforce Experience Cloud Course Catalog</a></td><td>Show fall courses in a three-column Avonni AX - Gallery on Salesforce Experience Cloud, with photos, dates, prices and available seats from course records.</td><td><a href="https://2929066058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDL6JQuZArjJeQvX2ot4y%2Fuploads%2FaaH2KyU8N9rvF6OJKTaD%2Ftutorial-fall-course-catalog.webp?alt=media">tutorial-fall-course-catalog.webp</a></td><td><a href="https://docs.avonnicomponents.com/projects/use-cases/portals-and-partner-sites/fall-course-catalog.md">Build a Salesforce Experience Cloud Course Catalog</a></td></tr></tbody></table>

## Getting Started

Use this simple tutorial to learn the basics of the Gallery component and start building your use cases.

{% @arcade/embed url="<https://app.arcade.software/share/QrGyk84126ycSIM6P0oX>" flowId="QrGyk84126ycSIM6P0oX" %}

## Configuration

### Data Source

The **Data Source** is where you define your gallery's content. AX - Gallery supports two data source types: **Manual** and **Query**.

<figure><img src="https://2929066058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDL6JQuZArjJeQvX2ot4y%2Fuploads%2Fgit-blob-ed6a00bc166f7e8986aa8696895a09bfd59eb62a%2F2024-02-07_21-14-11.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

| Data Source Type | Description                                                                                                                                                             | When to Use                                                                                                                                      |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Manual**       | Upload or enter each gallery item directly in the component. Every image added through the Media Source picker creates a **new** file in your Salesforce Files library. | One-off galleries with static content that rarely changes (landing page hero, fixed product showcase, demos).                                    |
| **Query**        | Pull items dynamically from a Salesforce object (Product, Knowledge, ContentVersion, custom object…). The gallery auto-updates when the underlying records change.      | Any content that needs to stay in sync with Salesforce data, rotate regularly, or be managed by a non-technical team outside Experience Builder. |

{% hint style="info" %}

#### **Choosing between Manual and Query**

Manual mode creates a **brand new file** in the library every time you upload an image. It does not reference files that already exist in Salesforce Files. If you need to reuse or update your gallery content without reopening the Properties Panel, use **Query** instead.
{% endhint %}

#### Model Sharing with Avonni AX - Gallery

**Adherence to Salesforce Data Sharing Rules:**

* **Respecting Org Settings:** Avonni Components fully comply with your Salesforce organization's existing data-sharing configurations and access settings.
* **No Interference Policy:** These components do not alter or affect your pre-established data-sharing rules in any way.
* **Controlled Visibility and Access:** The ability to view and interact with records through Avonni Components is governed by your organization's defined sharing settings and user permissions

### Using existing Salesforce Files as your Media Source

The **Media Source** field in AX - Gallery is flexible about what you feed it. You can map it to a URL, a ContentDocumentId, or a full Salesforce Files download path. The component automatically detects ContentDocumentIds and resolves them to the correct preview URL at render time.

This is how you keep a gallery pointing at files in the **Salesforce Files library** without ever re-uploading through the component.

| What you put in Media Source                                                                            | What the gallery renders                                                                         |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| A field containing a **ContentDocumentId** (starts with `069…`)                                         | The latest version of the file is resolved and displayed. The component auto-detects `069…` IDs. |
| The standard **VersionDataURL** field when querying `ContentVersion`                                    | The file is downloaded and displayed. Recommended when your source object is ContentVersion.     |
| A **Shepherd URL** built with an expression like `/sfc/servlet.shepherd/version/download/{{Record.Id}}` | The exact version referenced in the URL is displayed. Useful for custom URL construction.        |
| A **Public URL** (external image hosted elsewhere)                                                      | The image is loaded from the external source.                                                    |

#### **How to set it up in Query mode**

1. In the **Data Source**, select **Query** and choose your source object (`ContentVersion`, a custom object holding file references, or any object with an image field).
2. Apply a filter that identifies which records should appear (by title convention, tag, custom field, picklist value, etc.).
3. In **Data Mappings**, map **Media Source** based on your source object :
   * **Querying ContentVersion :** map Media Source to the standard `Version Data URL` field.
   * **Querying a custom object with a ContentDocumentId field :** map Media Source directly to that field (the component auto-detects `069…` IDs and resolves them).
   * **Querying any object with a full image URL field :** map Media Source directly to that field.

Once configured, updating your gallery's content is as simple as replacing the files in the Salesforce Files library or updating the reference field on your records.

{% hint style="info" %}

#### Experience Builder Preview

Images pointing to Salesforce Files may not render in the Experience Builder preview because the builder does not authenticate as a portal user. They will render correctly once logged in to the published site as a community user
{% endhint %}

### Properties

**API Name** gives the component a unique identifier used to reference it (3 to 30 characters; letters, digits, underscores and dashes).

**Caption**, **Title** and **Content** are the component-level texts shown once above the items — a short caption, the heading, and the body text below it. Each has its own text style setting beside it — **Caption Text Style**, **Title Text Style** and **Content Text Style** — offering `Heading 1` to `Heading 4` and `Paragraph 1` / `Paragraph 2`.

**Media Position** places each item's media relative to that content: `Top Left`, `Top Center` (the default), `Top Right`, `Left`, `Right`, `Bottom Left`, `Bottom Center` or `Bottom Right`.

**Number of Columns** sets how many items are shown side by side — in the `Carousel` variant, how many sit on one panel. It defaults to 1.

**No Results Message** replaces the default empty state with your own text when the data source returns no items, and **No Results Message Attributes** controls what that empty state shows — **Hide No Results Image** drops the illustration, **Hide No Results Message** drops the text. Both are off by default.

### Carousel

**Carousel** holds the settings for the `Carousel` variant:

* **Indicator Variant**: the look of the progress indicators, `Base` (the default) or `Shaded`.
* **Hide Indicator**: hides the progress indicator.
* **Hide Navigation**: hides the left and right arrows.
* **Is Infinite**: loops back to the first item after the last one.
* **Disable Auto Refresh**: stops the carousel looping after the last image.
* **Disable Auto Scroll**: stops the automatic scrolling, so users move through the items with the indicators.
* **Scroll Duration**: how long each image is shown before the next one, 5 seconds by default.

### Variant

**Variant** chooses the layout the items are rendered in: `Carousel` (the default), `Tabs`, `Grid` or `Gallery`. Every variant shows the same per-item fields — **Title**, **Description** and **Media Source** — and runs the item's **Link To** interaction when it is clicked.

#### **Carousel**

Items are shown one panel at a time, as a slideshow. **Number of Columns** sets how many items share a panel on a wide container; on a narrow one, each panel holds a single item.

<figure><img src="https://2929066058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDL6JQuZArjJeQvX2ot4y%2Fuploads%2Fgit-blob-52d1c70cb5a9a01aa278e12e19ec733f9eb218c9%2F2024-02-07_21-17-09.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

The panel advances on its own every **Scroll Duration** (5 seconds by default) unless **Disable Auto Scroll** is on, and **Is Infinite** loops from the last panel back to the first. Below the panels sit the progress indicators, and previous / next arrows sit on either side; **Hide Indicator** and **Hide Navigation** remove them. All of these are set in the **Carousel** section.

#### **Tabs**

Each item becomes a tab, labelled with the item's **Title** and subtitled with its **Description**. Selecting a tab shows that item's media, placed according to **Media Position**; only the selected item is shown at a time.

<figure><img src="https://2929066058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDL6JQuZArjJeQvX2ot4y%2Fuploads%2Fgit-blob-da7af562b2ec8870f5d77aac546950f983de801f%2F2024-02-07_21-18-03.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

**Media Position** also sets the direction of the tab strip: `Left` or `Right` stacks the tabs vertically next to the media, with the component-level **Caption**, **Title** and **Content** beside them; every other position lays the tabs out horizontally, with those three texts above them.

#### **Grid**

Items are laid out in rows of equal-width cells, **Number of Columns** per row, filling each row left to right before starting the next. Every item is shown at once; nothing is hidden behind navigation.

#### **Gallery**

Items are distributed down **Number of Columns** columns, each column stacking its items vertically, so items of different heights sit flush against the one above instead of lining up in rows. As with **Grid**, every item is shown at once.

## Interactions

The "Link to" section determines what happens when a user clicks on an item in your Avonni Gallery. Use this to direct users to detailed pages, open new content, or trigger other actions.

**Example:**

* For example, showcase featured houses in a gallery and allow users to click on each image to view more details on a separate page.

## Styling

The styling attributes let you control the visual appearance of every element in the gallery. Settings are grouped by what they affect.

<figure><img src="https://2929066058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDL6JQuZArjJeQvX2ot4y%2Fuploads%2Fgit-blob-183fc0740d29bd4d169d916e324ae5fd28c93136%2F2024-02-07_21-18-53.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

{% tabs %}
{% tab title="General" %}
Applies to every variant.

| Setting         | What it controls                                                                        |
| --------------- | --------------------------------------------------------------------------------------- |
| **Size**        | Width, height and overflow of the component.                                            |
| **Border**      | Color, size, style and radius of the border around the component.                       |
| **Margin**      | Outer spacing around the component.                                                     |
| **Padding**     | Inner spacing of the component.                                                         |
| **Caption**     | Color, font and line clamp of the component-level **Caption**.                          |
| **Title**       | Color, font, horizontal alignment and line clamp of the component-level **Title**.      |
| **Content**     | Color, font and horizontal alignment of the component-level **Content**.                |
| **Media**       | **Object Fit** — how each item's image or video fills its box.                          |
| **Flow Dialog** | **Flow Dialog Header** and **Flow Dialog Footer** of a flow dialog opened from an item. |
| {% endtab %}    |                                                                                         |

{% tab title="Items" %}
Applies to the **Carousel**, **Grid** and **Gallery** variants — in the **Tabs** variant the items are tabs, styled under **Tabs**.

| Setting                                    | What it controls                                                                            |
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| **Gallery/Grid/Carousel Item**             | Background color, border (color, size, style, radius) and content border radius of an item. |
| **Gallery/Grid/Carousel Item Title**       | Color, font and line clamp of each item's title.                                            |
| **Gallery/Grid/Carousel Item Description** | Color and font of each item's description.                                                  |
| **Gallery/Grid/Carousel Image**            | Background color, height and radius of each item's media.                                   |
| {% endtab %}                               |                                                                                             |

{% tab title="Carousel" %}
Only applies when **Variant** is set to `Carousel`.

| Setting                         | What it controls                                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Carousel Active Indicator**   | Background and border of the indicator for the panel in view, including its **Shaded** variant.         |
| **Carousel Inactive Indicator** | The same settings for the other panels' indicators.                                                     |
| **Carousel Navigation Button**  | Background, icon and border of the previous / next buttons, in their normal, hover and disabled states. |
| {% endtab %}                    |                                                                                                         |

{% tab title="Tabs" %}
Only applies when **Variant** is set to `Tabs`.

| Setting                     | What it controls                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Tab**                     | Vertical alignment, width, height, line height and left / right spacing of each tab.                         |
| **Tab Border**              | Size and color of the border around each tab.                                                                |
| **Tab Active/Hover Border** | The same two settings for the active tab and the hover state.                                                |
| **Tab Background**          | Background color of the active tab and of the hover state.                                                   |
| **Tab Label**               | Color, font and text shadow of the tab labels (the items' **Title**), each with an active and a hover value. |
| **Tab Subtitle**            | The same settings for the tab subtitles (the items' **Description**).                                        |
| {% endtab %}                |                                                                                                              |
| {% endtabs %}               |                                                                                                              |

## Troubleshooting

| Problem                                                                                     | Cause                                                                                                                                                                                           | Fix                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Images do not preview in Experience Builder but display correctly on the published site** | Experience Builder does not authenticate as a portal user, so it cannot fetch images from Salesforce Files during preview.                                                                      | Expected behavior. Log in to the published site as a community user to verify images render correctly.                                                                                                                                     |
| **"No preview available" appears in Manual mode**                                           | The uploaded image was not flagged as a public link, so portal users cannot load it.                                                                                                            | Re-upload the image and check **Public link** at upload time, or switch to Query mode where standard sharing rules apply.                                                                                                                  |
| **Manual mode forces you to re-upload every time you want to change an image**              | Manual mode is a direct uploader — it does not reference existing Salesforce Files.                                                                                                             | Use **Query** mode with ContentVersion or a custom object holding file references. See *Using existing Salesforce Files as your Media Source* above.                                                                                       |
| **Gallery is empty for portal users but works in Experience Builder preview**               | The portal user's profile lacks access to the queried object or to the referenced files.                                                                                                        | Check profile object permissions, field-level security, and Library/sharing access on `ContentVersion` or the source object.                                                                                                               |
| **Images do not render at all (neither in preview nor on the published site)**              | Media Source is mapped to a field that does not contain a valid file reference (ContentDocumentId starting with `069…`, the `Version Data URL` field on ContentVersion, or a public image URL). | Verify what the mapped field actually contains. When querying ContentVersion, use the standard `Version Data URL` field. For custom objects, store a ContentDocumentId (starting with `069…`) and map Media Source directly to that field. |
| **Gallery shows correct titles but all images are broken**                                  | Media Source is mapped to a field that does not contain a ContentDocumentId or a valid URL.                                                                                                     | In Data Mappings, confirm Media Source points to a ContentDocumentId field, a shepherd URL, or a valid public image URL.                                                                                                                   |

## Use Cases

### Example 1: Customer News Carousel

{% @arcade/embed url="<https://app.arcade.software/share/pOjxSsq8rQ3YgZFvjMgr>" flowId="pOjxSsq8rQ3YgZFvjMgr" %}

Keep your customers informed and engaged by showcasing your latest articles directly on your Experience Cloud home page. The AX Gallery component makes it easy to display a dynamic, image-rich news carousel that updates automatically as new content is published.

***

#### **What You'll Achieve**

* **Fresh content at a glance:** Surface your most recent Knowledge articles on the home page, complete with images, so visitors never miss an update.
* **Effortless browsing:** Let customers scroll through company news in a clean, structured carousel layout.
* **Targeted filtering:** Display only News articles by leveraging a custom picklist field, keeping the carousel focused and relevant.

***

#### **Before You Begin**

* **`ImageId__c` field:** Create a Text field on the Knowledge object to store the Content Document ID of each article's image.
* **`Type__c` field:** Create a Picklist field on the Knowledge object to categorize articles, making sure the **News** value exists and is applied to your articles.

***

#### **How to Set It Up**

{% stepper %}
{% step %}

#### **Add the component to your page**

* Drag the **AX Gallery** component onto your desired page in Experience Builder.
  {% endstep %}

{% step %}

#### **Customize the component display**

* Set the **Title** to `News Carousel`.
* Set the **Caption** to `Browse our weekly articles`.
* Set the **Number of Columns** to `3`.
  {% endstep %}

{% step %}

#### **Set up your data source**

* Create a new query in the data source configuration.
* Select **Knowledge** as the object (make sure to select the second Knowledge option in the list).
* Add a filter: **Type\_\_c equals** `News`.
* Set the sort order to **Created Date, Descending** so your newest articles always appear first.
  {% endstep %}

{% step %}

#### **Configure the data mapping**

* Map **Title** to the Knowledge `Title` field.
* Map **Media Source** to `ImageId__c` to pull in article images.
* Set the **Playback Rate** to `5`.
  {% endstep %}

{% step %}

#### **Preview your work**

* Use the Experience Builder preview to confirm that your carousel displays the correct articles, images, and layout before publishing.
  {% endstep %}
  {% endstepper %}

***

### Example 2: Customer Products gallery

{% @arcade/embed url="<https://app.arcade.software/share/aIu9ZNuteXdewe19LJL0>" flowId="aIu9ZNuteXdewe19LJL0" %}

Give your customers a visually compelling way to discover your product catalog, right from your home page. By combining the AX Gallery component with your Product data, you can create an eye-catching carousel that highlights featured products and guides visitors straight to product detail pages.

***

#### **What You'll Achieve**

* **A visual product showcase:** Display featured headphones in a rich, image-forward carousel that encourages browsing.
* **Seamless navigation:** Allow customers to move from the carousel directly to individual product detail pages with ease.
* **A curated homepage experience:** Highlight the products that matter most by surfacing only your featured catalog on the home page.

***

#### **Before You Begin**

* **`Type__c` field:** Create a Picklist field on the Product2 object and ensure the **Headphone** value exists, so you can filter the carousel to the right products.
* **`ContentDocumentId__c` field:** Create a Text field on the Product2 object to store the image URL for each product.

***

#### **How to Set It Up**

{% stepper %}
{% step %}

#### **Add the component to your page**

* Drag the **AX Gallery** component onto your desired page in Experience Builder.
  {% endstep %}

{% step %}

#### **Customize the component display**

* Set the **Title** to `Products Carousel`.
* Set the **Caption** to `Browse our featured products!`
* Set the **Number of Columns** to `3`.
  {% endstep %}

{% step %}

#### **Set up your data source**

* Create a new query in the data source configuration.
* Select **Product** as the object.
  {% endstep %}

{% step %}

#### **Configure the data mapping**

* Map **Title** to the `Product Name` field.
* Map **Media Source** to `ContentDocumentId__c` to display each product's image.
* Set the **Playback Rate** to `5`.
  {% endstep %}

{% step %}

#### **Preview your work**

* Use the Experience Builder preview to confirm that your products, images, and carousel layout appear as expected before publishing.
  {% endstep %}
  {% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avonnicomponents.com/experience-cloud/experience-components/ax-gallery.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
