How to Configure Menu Category Banner Images

Menu Category Banner Image

The Menu Category Banner Image feature lets brand admins upload a custom image for each menu category. When enabled, the image is displayed as a visual header on the category in the web app, kiosk, and mobile app.

When not configured, the category falls back to the brand's primary color, exactly as it behaves today.

This is a fully backward-compatible, opt-in feature. Brands that do not configure a banner image see no visual change.

Accessing the Banner Image Section

1. Navigate to Menu > Categories.
2. Open any category's edit form.
3. Scroll to the Banner Image section.

Uploading a Desktop or Kiosk Banner

To upload a banner image for web and kiosk surfaces:

1. Click the upload area or the Upload Image button.
2. Select an image file.

Supported File Types

• JPG
• PNG
• WebP

File Size Limit

• Maximum file size: TBD (Engineering decision — recommended 5–10 MB)

Preview Behavior

• A thumbnail preview renders immediately after upload.
• The preview is displayed against the brand's primary color as the background.
• The preview reflects the final appearance on web and kiosk surfaces.

Enabling and Disabling a Banner

The Enable Banner toggle is only visible after an image has been uploaded for the category.

Enable Banner

• banner_image_enabled: true
• The image is shown on all supported surfaces.

Disable Banner

• banner_image_enabled: false
• The image is hidden.
• The brand's primary color is shown instead.
• The uploaded image is retained and can be re-enabled later.

Saving Changes

• Persists the toggle state.
• Reflects the correct state when the category is loaded again.

Uploading a Mobile-Specific Banner

A separate Mobile Banner Image upload slot appears below the desktop banner upload.

Why Use a Mobile Banner?

Mobile layouts are typically portrait or square. A dedicated mobile banner prevents cropping issues that can occur when using a wider desktop image on mobile devices.

Mobile Banner Rules

• Accepted formats and file size limits are the same as the desktop banner.
• The mobile image can be deleted independently of the desktop banner.
• If no mobile image is uploaded, the mobile app falls back to the desktop banner image, then to the brand primary color.

Replacing or Removing a Banner

Replace a Banner

• Upload a new image.
• The previous image is automatically removed.

Remove a Banner

• Click the Delete button next to the thumbnail preview.
• The preview is cleared.
• The image is removed from the API response.

Display Logic

Which Image Field Is Used on Each Surface?

Surface	Image Field
Web app	image.thumbnail_medium
Kiosk	image.thumbnail_medium
Mobile	image.fullsize (full resolution for retina displays)

When to Show a Banner Image vs. Color Fallback

Image	banner_image_enabled	Result
non-null	true or null	Show banner image
non-null	false	Show brand primary color
null	any	Show brand primary color

Color Fallback Rules

If the brand has not set a primary color:

1. Fall back to the secondary color.
2. If neither color is set, use the application default.

Mobile Fallback Chain

The mobile application uses the following fallback order:

1. Mobile banner image (mobile_banner_image) if uploaded and enabled.
2. Desktop banner image (image) if uploaded and enabled.
3. Brand primary color.

Image Requirements

Property	Value
Accepted formats	JPG, PNG, WebP
Max file size	1 MB
Desktop/kiosk aspect ratio	2114 x 288 pixels
Mobile aspect ratio	2114 x 288 pixels

Additional Guidance

Recommended dimensions and aspect ratio guidance will be displayed in the Management Centre upload UI once finalised.