> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Media field

> Detailed explanation of the Media field in ButterCMS, including input, output, configuration options, use cases, and the ButterCMS Media Library

The **Media** field allows you to add media from your Media Library—including images, documents, PDFs, audio, and videos—to your Pages and Collections.
<Tip>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.</Tip>

## Field at a glance

### Input and output

<CardGroup cols={2}>
  <Card title="Input type" icon="arrow-right-to-bracket">
    File picker with search and preview (select from Media Library)
  </Card>

  <Card title="API output" icon="arrow-right-from-bracket">
    * without alt text: `string` (URL to asset in Media Library CDN)
    * with alt text: `object` with two key-value pairs: `url` and `alt`
  </Card>
</CardGroup>

### API response example

#### Without alt text

```json theme={null}
{
  "hero_image": "https://cdn.buttercms.com/abc123xyz"
}
```

#### With alt text

<Tip>
  Include `alt_media_text=1` in your API request to fetch assets with alt text.
</Tip>

```json theme={null}
{
  "hero_image": {
    "url": "https://cdn.buttercms.com/abc123xyz",
    "alt": "Team collaboration meeting in modern office"
  }
}
```

### Field configuration options

<Tip>
  Checking the `default value` box in the field configuration options will allow you to set a default Media asset for the field.
</Tip>

| `Option name` | `Type`  | `Function`                                   |
| ------------- | ------- | -------------------------------------------- |
| Required?     | boolean | Make field required to save page             |
| Help text     | string  | Add help text to describe usage to your team |
| Default value | boolean | Set a default value for the field            |

## Common use cases

<CardGroup cols={2}>
  <Card title="Page content">
    * Hero/banner images
    * Featured images
    * Author photos
    * Thumbnails
    * Background images
  </Card>

  <Card title="Products">
    * Product photos
    * Gallery images
    * Variant images
    * Size charts
    * Brand logos
  </Card>

  <Card title="Blogs & articles">
    * Featured images
    * Inline content images
    * Author avatars
    * Social sharing images
  </Card>

  <Card title="Marketing">
    * Ad creatives
    * Promotional banners
    * Logo variations
    * Icons and badges
  </Card>
</CardGroup>

## Key features

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

<CardGroup cols={2}>
  <Card title="Media library overview" icon="photo-film" href="../../create-content/media-management/media-library-overview">
    Explore your ButterCMS media library, including sorting, uploading, searching, and tagging media.
  </Card>

  <Card title="Alt text for accessibility and SEO" icon="universal-access" href="../../create-content/media-management/alt-text">
    How to add alt text to images and retrieve from our API.
  </Card>

  <Card title="CDN & performance" icon="globe" href="../../build-your-app/media-cdn/customizing-media-urls">
    Learn about our Media CDN, including how to customize your URLs
  </Card>

  <Card title="Image transformations" icon="wand-magic-sparkles" href="../../create-content/media-management/image-editing-transformations">
    How to transform your images: flip, rotate, resize, crop, add filters and effects, and more!
  </Card>

  <Card title="Dynamic image resizing" icon="up-right-and-down-left-from-center" href="../../create-content/media-management/image-editing-transformations#responsive-images">
    How to leverage our CDN's `resize` task to create responsive images in your app.
  </Card>

  <Card title="Automatic image compression" icon="compress-arrows-alt" href="../../create-content/media-management/automatic-image-compression-webp">
    Learn about ButterCMS's automatic image compression, including how to switch back to the original image size and format.
  </Card>
</CardGroup>

## 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

<Tabs>
  <Tab title="JavaScript/React">
    ```javascript theme={null}
    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"
        />
      );
    }
    ```
  </Tab>

  <Tab title="Next.js with Image Optimization">
    ```javascript theme={null}
    import Image from 'next/image';

    function ProductImage({ product }) {
      return (
        <Image
          src={product.image}
          alt={product.image_alt || product.name}
          width={800}
          height={600}
          placeholder="blur"
          blurDataURL={`${product.image}?blur=50`}
        />
      );
    }
    ```
  </Tab>
</Tabs>