✨ Features

• 🚀 Auto-optimized — AVIF → WebP → fallback format selection (30-50% smaller)
• 🎯 Zero CLS — Prevents layout shift with aspect ratio
• 📘 Type-safe — Full TypeScript support with strict types
• ⚡ Modern — Svelte 5 runes ($state, $derived, $effect)
• 📱 Responsive — Automatic srcset with configurable DPR support
• 🌐 CDN-ready — Works with Cloudflare, Imgix, or any image CDN
• 🪶 Lightweight — Zero runtime dependencies, tree-shakeable
• ✅ Production-tested — 55 unit tests, 100% type coverage
• 🔒 Secure — XSS-safe with strict input validation

📦 Installation

npm install @7haven/h-image

# Yarn
yarn add @7haven/h-image

# pnpm
pnpm add @7haven/h-image

# Bun
bun add @7haven/h-image

🚀 Quick Start

<script>
	import { Image, configureCdn } from '@7haven/h-image';

	// Optional: Configure your CDN
	configureCdn({ baseUrl: 'https://cdn.example.com' });
</script>

<!-- Auto-optimized: AVIF → WebP → fallback -->
<Image src="file/hero" alt="Hero image" width={1200} aspectRatio="21/9" />

That's it! The component automatically:

• ✅ Generates AVIF and WebP versions
• ✅ Creates responsive srcset
• ✅ Prevents layout shift
• ✅ Lazy loads by default

📖 Usage Examples

Hero Image (LCP Optimization)

<Image
	src="file/hero"
	alt="Hero banner"
	width={1920}
	aspectRatio="21/9"
	fetchpriority="high"
	loading="eager"
/>

Product Grid

<Image
	src="file/product"
	alt="Product thumbnail"
	width={400}
	aspectRatio="1/1"
	transform={{ quality: 85 }}
/>

Art Direction

Different images for different screen sizes:

<Image
	src="file/fallback"
	alt="Responsive hero"
	width={1200}
	sources={[
		{ src: 'file/desktop-wide', media: '(min-width: 768px)' },
		{ src: 'file/mobile-square', media: '(max-width: 767px)' }
	]}
/>

Image Transforms

<Image
	src="file/photo"
	alt="Enhanced photo"
	width={800}
	transform={{
		blur: 10,
		brightness: 1.2,
		quality: 90
	}}
/>

⚙️ Props

| Prop | Type | Default | Description | | --------------- | -------------------------------- | ------------ | ------------------------------------ | | src | string | required | Image source (CDN path or URL) | | alt | string | required | Alt text for accessibility | | width | number | - | Display width in pixels | | height | number | - | Display height in pixels | | aspectRatio | string \| number | - | Aspect ratio (e.g., "16/9", 1.5) | | modernFormats | boolean | true | Auto-generate AVIF/WebP sources | | sources | ImageSource[] | - | Custom sources for art direction | | transform | TransformOptions | {} | CDN transformation options | | loading | 'lazy' \| 'eager' | 'lazy' | Loading strategy | | fetchpriority | 'high' \| 'low' \| 'auto' | - | Resource priority hint | | placeholder | 'blur' \| 'none' \| string | 'blur' | Placeholder while loading | | fit | 'cover' \| 'contain' \| 'fill' | - | Object-fit behavior | | position | string | 'center' | Object-position value | | sizes | string | auto | Custom sizes attribute | | class | string | - | Additional CSS classes |

🎨 Advanced Usage

Custom Sizes Attribute

<Image src="file/hero" alt="Hero" width={1200} sizes="(min-width: 1024px) 50vw, 100vw" />

Object Fit & Position

<Image
	src="file/portrait"
	alt="Person"
	width={400}
	height={400}
	fit="cover"
	position="top center"
/>

Disable Modern Formats

<Image src="file/legacy" alt="Legacy browser support" width={800} modernFormats={false} />

Custom Placeholder

<Image src="file/hero" alt="Hero" width={1200} placeholder="data:image/svg+xml,..." />

💡 Best Practices

Performance

• ✅ Always provide width + height OR aspectRatio to prevent CLS
• ✅ Use fetchpriority="high" + loading="eager" for LCP images only
• ✅ Keep modernFormats={true} (default) for 30-50% smaller file sizes
• ✅ Customize sizes attribute for responsive layouts
• ✅ Use quality: 85 for optimal size/quality balance
• ✅ Component uses CSS contain for rendering performance

Security

• 🔒 XSS-safe URL construction (native URL API)
• 🔒 Strict input validation on all parameters
• 🔒 EXIF metadata automatically stripped by CDN
• 🔒 No script injection vulnerabilities
• 🔒 Type-safe props prevent invalid configurations

Accessibility

• ♿ alt text is required (TypeScript enforced)
• ♿ Semantic HTML (<picture>, <img>)
• ♿ Native keyboard navigation support
• ♿ Screen reader friendly
• ♿ ARIA roles supported via role prop

🔧 Configuration

CDN Setup

import { configureCdn } from '@7haven/h-image';

// Configure once in your root layout
configureCdn({
	baseUrl: 'https://cdn.example.com'
});

Available Transforms

| Transform | Type | Description | | ------------ | -------------------------------- | ----------------- | | format | 'avif' \| 'webp' \| 'auto' | Output format | | width | number | Resize width | | height | number | Resize height | | fit | 'cover' \| 'contain' \| 'fill' | Resize behavior | | quality | number (1-100) | Image quality | | blur | number | Blur intensity | | sharpen | number | Sharpen intensity | | brightness | number | Brightness level | | contrast | number | Contrast level | | saturation | number | Saturation level | | rotate | number | Rotation degrees |

Default Breakpoints

[400, 800, 1200, 1600] + // Standard
	2048; // When zoom={true}

📚 API Reference

Components

import { Image } from '@7haven/h-image';

Configuration

import { configureCdn, getCdnConfig } from '@7haven/h-image';

// Configure CDN
configureCdn({ baseUrl: 'https://cdn.example.com' });

// Get current config
const config = getCdnConfig();

Utilities

import {
	buildImageUrl, // Build CDN URL
	generateSrcset, // Generate srcset string
	generateSizes, // Generate sizes attribute
	calculateHeight, // Calculate height from aspect ratio
	generateBlurPlaceholder // Generate blur placeholder
} from '@7haven/h-image';

Version

import { COMPONENT_VERSION } from '@7haven/h-image';

console.log(COMPONENT_VERSION); // '1.0.0'

TypeScript Types

import type {
	ImageProps, // Component props
	ImageSource, // Source object for art direction
	TransformOptions, // CDN transform options
	ImageFormat, // 'avif' | 'webp' | 'auto'
	FetchPriority, // 'high' | 'low' | 'auto'
	PlaceholderType, // 'blur' | 'none'
	CdnConfig // CDN configuration
} from '@7haven/h-image';

🌐 CDN Compatibility

Works with any CDN that supports image transformations via query parameters:

• ✅ Cloudflare R2 with Image Resizing
• ✅ Imgix
• ✅ Cloudinary
• ✅ Vercel Image Optimization
• ✅ Custom CDN (as long as it supports query params)

// Example: Cloudflare R2
configureCdn({ baseUrl: 'https://cdn.7haven.online' });

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 🐛 Report bugs — Open an issue with reproduction steps
2. 💡 Suggest features — Share your ideas for improvements
3. 🔧 Submit PRs — Fix bugs or add features
4. 📖 Improve docs — Help make documentation clearer

📄 License

MIT © 7Haven

🙏 Acknowledgments

Built with:

• Svelte 5 — The reactive framework
• TypeScript — Type safety
• Vitest — Testing framework