Image Component

The Image component displays images in your views. It supports static URLs, dynamic URLs from database fields, and formulas, with options for sizing, fit modes, and fallback images.

Overview

Use the Image component to:

• Display product photos, avatars, and logos
• Show images stored in your database
• Create visual galleries and catalogs
• Add branding and decorative elements

Adding an Image Component

1. Open the Layout tab in your app editor
2. Drag the Image component from the palette onto your canvas
3. Select the component to open the settings panel
4. Configure the source, sizing, and styling options

Settings

Setting	Type	Description
Source	URL/Formula	Image URL or formula returning URL
Alt Text	Text/Formula	Accessibility text for screen readers
Fit Mode	Dropdown	How image fits within container
Border Radius	Number	Corner rounding in pixels
Fallback Image	URL	Shown if source fails to load

Image Source

Static URL

Enter a direct URL to an image:

Source: https://example.com/images/logo.png

Dynamic URL from Database

Reference an image URL field from your data:

Source: {{$row.image_url}}

Source: {{products.thumbnail}}

Conditional Image

Use formulas to select different images:

Source: {{IF($row.status = 'active',
  'https://example.com/active-icon.png',
  'https://example.com/inactive-icon.png')}}

User Avatar

Display the current user’s avatar:

Source: {{$user.avatar_url}}

Constructed URLs

Build URLs dynamically:

Source: {{'https://storage.example.com/' + $row.image_path}}

Source: {{'https://ui-avatars.com/api/?name=' + $row.name}}

Fit Modes

Control how images fill their container:

Mode	Description	Best For
contain	Entire image visible, may have letterboxing	Logos, icons, product photos
cover	Fills container, may crop edges	Backgrounds, hero images
fill	Stretches to fill (may distort)	Rarely used
none	Natural size, may overflow	When exact size matters

Choosing the Right Fit Mode

contain: Product images where the full item must be visible
cover: Avatar images, background images, hero sections
fill: Rarely appropriate, causes distortion
none: Technical images, exact pixel requirements

Alt Text

Provide descriptive alt text for accessibility:

Static Alt Text

Alt Text: Company Logo

Dynamic Alt Text

Alt Text: Photo of {{$row.product_name}}

Alt Text: {{$user.display_name}}'s profile picture

Best Practices for Alt Text

• Describe the image content, not just “image of…”
• Keep it concise but descriptive
• For decorative images, alt text can be empty
• Include relevant details visible in the image

Border Radius

Round the corners of your images:

Value	Result
0	Square corners (default)
4-8	Slightly rounded
16-24	Noticeably rounded
50%	Circular (for square images)

Common Patterns

Avatar: border-radius: 50% (or 9999 for fully round)
Card image: border-radius: 8
Thumbnail: border-radius: 4

Fallback Image

Specify an image to show when the source fails to load:

Fallback Image: https://example.com/placeholder.png

Use Cases

• Placeholder when database field is empty
• Default avatar for users without photos
• “Image not found” indicator
• Branded placeholder maintaining layout

Fallback Strategies

Avatar fallback: Generic user silhouette
Product fallback: "No image available" placeholder
Logo fallback: Text-only version or empty

Sizing

Component Dimensions

Control the image container size:

• Width: Set in pixels or percentage
• Height: Set in pixels, percentage, or auto

Aspect Ratio

Maintain consistent proportions:

Width: 100%
Height: auto (maintains aspect ratio)

For fixed aspect ratios, use CSS or container sizing.

Common Sizes

Use Case	Suggested Size
Avatar (small)	32x32 or 40x40
Avatar (large)	64x64 or 80x80
Thumbnail	100x100 or 150x150
Card image	300x200 or full width
Hero image	Full width, 300-500px height

Visibility

Control when the image appears:

Visibility Formula: {{!ISNULL($row.image_url)}}

Hide the component when there’s no image to display.

Common Patterns

Product Photo

Source: {{$row.product_image}}
Alt Text: {{$row.product_name}}
Fit Mode: contain
Border Radius: 8
Fallback: https://example.com/no-product-image.png

User Avatar

Source: {{$row.avatar_url}}
Alt Text: {{$row.name}}'s profile picture
Fit Mode: cover
Border Radius: 9999 (circular)
Fallback: https://example.com/default-avatar.png

Company Logo

Source: {{$row.company_logo}}
Alt Text: {{$row.company_name}} logo
Fit Mode: contain
Border Radius: 0
Fallback: (empty - hide if no logo)

Hero Banner

Source: {{$row.banner_image}}
Alt Text: (empty for decorative)
Fit Mode: cover
Border Radius: 0
Width: 100%
Height: 300px

Icon/Status Indicator

Source: {{IF($row.status = 'success',
  '/icons/check-circle.svg',
  '/icons/x-circle.svg')}}
Alt Text: Status: {{$row.status}}
Fit Mode: contain
Size: 24x24

Linked Image

Wrap an image in a button to make it clickable:

1. Add a Button component with ghost variant
2. Set the button’s action (Navigate or Open URL)
3. Place the Image inside or use CSS to position

Or use the image in a List component with row click action.

Image Sources

Supported Formats

EmberBlocks supports common web image formats:

• JPEG/JPG: Photos, complex images
• PNG: Graphics, transparency
• GIF: Animations, simple graphics
• SVG: Icons, logos, scalable graphics
• WebP: Modern format, good compression

Storage Options

Images can be hosted on:

• Your database: Store URLs pointing to your CDN
• Supabase Storage: Built-in file storage
• External CDNs: Cloudinary, AWS S3, etc.
• Public URLs: Any accessible image URL

URL Best Practices

• Use HTTPS URLs for security
• Use CDN-hosted images for performance
• Consider image optimization services
• Store thumbnails separately for list views

Performance Tips

Image Optimization

• Use appropriately sized images (don’t load 4K for thumbnails)
• Serve WebP format when possible
• Use CDN with automatic optimization
• Lazy load images below the fold

Loading States

• Use fallback images as loading placeholders
• Consider skeleton loaders for large images
• Pre-cache frequently used images

Responsive Images

• Use percentage widths for fluid layouts
• Consider different image sizes for mobile
• Set max-width to prevent oversized images

Accessibility

Alt Text Guidelines

Image Type	Alt Text Approach
Informative	Describe the content and purpose
Decorative	Use empty alt text
Functional	Describe the action
Complex	Provide detailed description

Examples

// Informative
Alt: "Blue running shoes, side view"

// Decorative
Alt: ""

// Functional (image used as button)
Alt: "View full size image"

// Complex (chart/graph)
Alt: "Sales chart showing 20% growth Q1 2026"

Troubleshooting

Common Issues

Issue	Cause	Solution
Image not loading	Invalid URL	Verify URL is accessible
Wrong size	Fit mode issue	Try different fit modes
Broken image icon	404 or CORS error	Check URL, add fallback
Distorted image	Using ‘fill’ mode	Switch to ‘cover’ or ‘contain’
Slow loading	Large file size	Optimize images, use thumbnails

Debugging Tips

1. Test the URL directly in a browser
2. Check for CORS issues in browser console
3. Verify database field contains valid URL
4. Test fallback image separately
5. Check visibility formula if image doesn’t appear

CORS Issues

If images from external domains don’t load:

• The image server must allow cross-origin requests
• Use a CORS proxy for testing
• Host images on your own domain or CDN
• Check for mixed content (HTTP vs HTTPS)

Related Components

• List Component - Display images in lists and cards
• Text Component - Combine with image captions
• Button Component - Make images clickable

Next Steps

• Views - Organize image galleries in views
• Formulas - Dynamic image sources
• Data Sources - Store image URLs in your database