@7haven/h-image

@7haven/h-image

Production-ready Svelte 5 image component with automatic AVIF → WebP → fallback optimization

Type-safe • Zero Dependencies • Zero Layout Shift • CDN-Ready

✨ 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

Other package managers

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

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

📄 License

MIT © 7Haven

🙏 Acknowledgments

Built with:

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

_{Made with ❤️ by 7Haven}