Image Field

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

Basic Usage

Multiple Images

Field Schema

An image field is authored as ImageFieldMetadata (@object-ui/types), which is the source of truth for the key set: it extends BaseFieldMetadata with multiple, accept and maxSize, the spec's FieldSchema.maxSize in bytes. There is no key for a file count or for pixel dimensions, because the spec declares none and no widget enforces one. A stored image is the bare sys_file id the upload adapter minted, the same value shape the file field stores: see the File Field for the refusal when no id comes back, and for UploadedFileMetadata, the legacy inline shape an older record may still hold. An image the reader may not open ({ id, metadataRefused: true }) renders as a restricted lock tile, never a thumbnail; see Restricted files on the File Field.

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'],
  maxSize: 5 * 1024 * 1024,
};

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, cap the upload size and accept web-friendly formats:

{
  type: 'image',
  name: 'product_images',
  label: 'Product Photos',
  multiple: true,
  maxSize: 5242880,        // 5 MB
  accept: ['image/jpeg', 'image/png', 'image/webp']
}

Integration Notes

Uploads go through the ambient UploadProvider, exactly as for the File Field: the stored value is the sys_file id the adapter returns, and a pick whose adapter returns none is refused with "did not complete".

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