Skip to main content
The Media field allows you to add media from your Media Library—including images, documents, PDFs, audio, and videos—to your Pages and Collections.
If you select an image with the Media field, you’ll have the option to then add alt text, which can be included in the API response.

​
Field at a glance

​
Input and output

Input type

File picker with search and preview (select from Media Library)

API output

  • without alt text: string (URL to asset in Media Library CDN)
  • with alt text: object with two key-value pairs: url and alt

​
API response example

​
Without alt text

{
  "hero_image": "https://cdn.buttercms.com/abc123xyz"
}

​
With alt text

Include alt_media_text=1 in your API request to fetch assets with alt text.
{
  "hero_image": {
    "url": "https://cdn.buttercms.com/abc123xyz",
    "alt": "Team collaboration meeting in modern office"
  }
}

​
Field configuration options

Checking the default value box in the field configuration options will allow you to set a default Media asset for the field.
Option nameTypeFunction
Required?booleanMake field required to save page
Help textstringAdd help text to describe usage to your team
Default valuebooleanSet a default value for the field

​
Common use cases

Page content

  • Hero/banner images
  • Featured images
  • Author photos
  • Thumbnails
  • Background images

Products

  • Product photos
  • Gallery images
  • Variant images
  • Size charts
  • Brand logos

Blogs & articles

  • Featured images
  • Inline content images
  • Author avatars
  • Social sharing images

Marketing

  • Ad creatives
  • Promotional banners
  • Logo variations
  • Icons and badges

​
Key features

Explore key features of the Media Field, the ButterCMS Media Library, and our Image CDN.

Media library overview

Explore your ButterCMS media library, including sorting, uploading, searching, and tagging media.

Alt text for accessibility and SEO

How to add alt text to images and retrieve from our API.

CDN & performance

Learn about our Media CDN, including how to customize your URLs

Image transformations

How to transform your images: flip, rotate, resize, crop, add filters and effects, and more!

Dynamic image resizing

How to leverage our CDN’s resize task to create responsive images in your app.

Automatic image compression

Learn about ButterCMS’s automatic image compression, including how to switch back to the original image size and format.

​
Best practices

  1. Always add alt text to images: Critical for accessibility and SEO
  2. Optimize before upload: Compress images using tools like TinyPNG
  3. Use appropriate dimensions: Don’t upload 4000px images for thumbnails
  4. Leverage transformations: Use URL parameters for responsive images
  5. Consider lazy loading: Load images only when needed
  6. Test WebP support: Ensure fallbacks for older browsers

​
Working with images in your application

const butter = require('buttercms')('your-api-key');

// Fetch with alt text
const response = await butter.page.retrieve('*', 'landing-page', {
  alt_media_text: 1
});

const page = response.data.data.fields;

// React component with responsive images
function HeroImage({ image }) {
  // If alt text is enabled
  const imageUrl = typeof image === 'object' ? image.url : image;
  const altText = typeof image === 'object' ? image.alt : '';

  return (
    <img
      src={imageUrl}
      srcSet={`
        ${imageUrl.replace('cdn.buttercms.com/', 'cdn.buttercms.com/resize=width:640/')} 640w,
        ${imageUrl.replace('cdn.buttercms.com/', 'cdn.buttercms.com/resize=width:1280/')} 1280w,
        ${imageUrl} 1920w
      `}
      sizes="100vw"
      alt={altText}
      loading="lazy"
    />
  );
}