Image Field

The Image Field component provides an image upload interface with thumbnail previews, multiple image support, and visual file management.

An image field is authored as ImageFieldMetadata (@object-ui/types), which is the source of truth for the key set: it extends BaseFieldMetadata with the upload limits and the two pixel bounds. A stored image is UploadedFileMetadata, the same value shape the file field stores.

import type { ImageFieldMetadata } from '@object-ui/types';

const productPhotos: ImageFieldMetadata = {
  type: 'image',
  name: 'product_photos',
  label: 'Product Photos',
  multiple: true,
  accept: ['image/png', 'image/jpeg', 'image/webp'],
  max_size: 5 * 1024 * 1024,
  max_files: 8,
  max_width: 4096,
  max_height: 4096,
};

The value being edited, and the className / disabled a host supplies, are not metadata keys — they are runtime widget props. See Field Widget Props.

Accepted Image Types

By default, accepts all common image formats:

// Default: 'image/*'
// Specific formats:
accept: ['image/png', 'image/jpeg', 'image/gif', 'image/webp']

Features

Thumbnail Grid: Images displayed in 4-column grid
Preview: Visual thumbnails for uploaded images
Hover to Remove: Delete button appears on hover
Batch Upload: Multiple image selection
Size Restrictions: Configurable file size limits

Cell Renderer

In tables/grids, displays image thumbnails:

import { ImageCellRenderer } from '@object-ui/fields';

// Shows up to 3 thumbnails plus count if more

Image Optimization

For best results, consider:

{
  type: 'image',
  name: 'product_images',
  label: 'Product Photos',
  multiple: true,
  max_size: 5242880,        // 5MB
  max_files: 10,
  max_width: 2048,
  max_height: 2048,
  accept: ['image/jpeg', 'image/png', 'image/webp']
}

Integration Notes

This component creates object URLs for preview. For production use, implement server-side upload:

const uploadImage = async (file: File) => {
  // Validate dimensions
  const img = new Image();
  img.src = URL.createObjectURL(file);
  await new Promise((resolve) => {
    img.onload = resolve;
  });
  
  if (img.width > maxWidth || img.height > maxHeight) {
    throw new Error('Image dimensions too large');
  }
  
  // Upload to server
  const formData = new FormData();
  formData.append('image', file);
  const response = await fetch('/api/images', {
    method: 'POST',
    body: formData
  });
  
  return response.json();
};

Use Cases

User Profiles: Avatar/profile pictures
Product Catalogs: Product images, SKU photos
Photo Galleries: Image collections, portfolios
Content Management: Blog post images, media assets
Real Estate: Property photos, listings

Image Field

Basic Usage

Basic Image Upload

Multiple Images

Multiple Image Upload

Field Schema