# Image Component

A semantic image component for displaying images with built-in responsive behavior, lazy loading, and accessibility features.

## Import path
```tsx
import Image from '@hubspot/cms-component-library/Image';
```

## Purpose

The Image component provides a standardized way to display images in HubSpot CMS projects with proper accessibility, responsive behavior, and performance optimization. It handles common image rendering concerns like lazy loading, responsive sizing, and semantic HTML attributes.

## Component Structure

```
Image/
├── index.tsx                     # Main component with render logic
├── types.ts                      # TypeScript type definitions
├── ContentFields.tsx             # HubSpot field definitions for content
├── index.module.scss             # CSS module with design tokens
└── stories/
    ├── Image.stories.tsx         # Usage examples in Storybook
    ├── ImageDecorator.tsx        # Storybook decorator
    └── ImageDecorator.module.css # Decorator styles
```

## Props

```tsx
{
  src: string;                                   // Image source URL (required)
  alt: string;                                   // Alternative text for accessibility (required)
  title?: string;                                // Tooltip text on hover
  width?: number;                                // Image width in pixels
  height?: number;                               // Image height in pixels
  loading?: 'lazy' | 'eager' | 'disabled';       // Loading strategy (default: 'lazy')
  responsive?: boolean;                          // Enable responsive scaling (default: true)
  className?: string;                            // Additional CSS classes
  style?: React.CSSProperties;                   // Inline styles (including CSS variables)
  variant?: 'primary' | 'secondary' | 'tertiary'; // Visual style variant
}
```

## Usage Examples

### Basic Image

```tsx
import Image from '@hubspot/cms-component-library/Image';

<Image
  src="https://example.com/image.jpg"
  alt="Description of the image"
  width={800}
  height={600}
/>
```

### Responsive Image

```tsx
<Image
  src="https://example.com/hero-image.jpg"
  alt="Hero banner showcasing product features"
  width={1200}
  height={600}
  responsive={true}
/>
```

### With Title Tooltip

```tsx
<Image
  src="https://example.com/product.jpg"
  alt="Product showcase"
  title="Click to view product details"
  width={600}
  height={400}
/>
```

### Eager Loading (Above the Fold)

```tsx
<Image
  src="https://example.com/hero.jpg"
  alt="Hero image"
  width={1920}
  height={1080}
  loading="eager"
  responsive={true}
/>
```

### With Custom Styling

```tsx
<Image
  src="https://example.com/profile.jpg"
  alt="User profile picture"
  width={200}
  height={200}
  style={{
    borderRadius: '50%',
    border: '4px solid #0066cc',
  }}
/>
```

## HubSpot CMS Integration

### Field Definitions

The Image component provides field definitions for easy integration with HubSpot CMS modules.

#### ContentFields

Configurable props for customizing field labels, names, and defaults:

```tsx
<Image.ContentFields
  imageLabel="Hero image"
  imageName="heroImage"
  imageDefault={{
    src: '',
    alt: '',
    width: 800,
    height: 600,
    loading: 'lazy',
  }}
  showLoading={true}
  resizable={true}
  responsive={true}
/>
```

**Fields:**
- `image`: ImageField for image source, alt text, dimensions, and loading strategy
- `showLoading`: Toggle to display loading strategy options in the editor
- `resizable`: Enable image resizing in the editor
- `responsive`: Enable responsive scaling by default

#### Style Fields

**Note:** There are no style fields included in this component. Do not try to consume or import style fields from the image component.

### Module Usage Example

```tsx
import Image from '@hubspot/cms-component-library/Image';

export default function HeroModule({ fieldValues }) {
  return (
    <Image
      src={fieldValues.heroImage?.src}
      alt={fieldValues.heroImage?.alt}
      width={fieldValues.heroImage?.width}
      height={fieldValues.heroImage?.height}
      loading={fieldValues.heroImage?.loading || 'lazy'}
      responsive={true}
    />
  );
}
```

## Styling

### CSS Variables

The Image component uses CSS variables for theming and customization:

**Base Styles:**
- `--hscl-image-display`: Display property (default: inline-block)
- `--hscl-image-borderRadius`: Border radius (default: 0)
- `--hscl-image-borderStyle`: Border style (no default)
- `--hscl-image-borderWidth`: Border width (no default)
- `--hscl-image-borderColor`: Border color (no default)
- `--hscl-image-boxShadow`: Box shadow (no default)

### Responsive Behavior

When `responsive={true}` (default), the image will:
- Scale down to fit container width while maintaining aspect ratio
- Never exceed its natural dimensions
- Use `max-inline-size: 100%` and `block-size: auto`


## Accessibility

The Image component follows accessibility best practices:

- **Required Alt Text**: The `alt` prop is required for screen reader accessibility
  - Descriptive alt text should explain what the image shows
  - For decorative images, use an empty string: `alt=""`
- **Semantic HTML**: Renders native `<img>` elements with proper attributes
- **Title Attribute**: Optional `title` prop provides additional context on hover
- **Dimensions**: `width` and `height` props help browsers allocate space and prevent layout shift

## Best Practices

- **Always provide meaningful alt text**: Describe the content and purpose of the image for screen readers
- **Use lazy loading for below-the-fold images**: Keep the default `loading="lazy"` for images not immediately visible
- **Use eager loading for above-the-fold images**: Set `loading="eager"` for hero images and critical content
- **Specify dimensions**: Always provide `width` and `height` to prevent cumulative layout shift (CLS)
- **Enable responsive behavior**: Keep `responsive={true}` (default) unless you need fixed dimensions
- **CSS Variables for consistent styling**: Use CSS variables rather than inline styles for site-wide theming
- **Style fields**: The image component doesn't include style fields. Do not try to import them.

## Related Components

- **Link**: Wrap Image with Link component to create clickable images
