Embedding Images
Use the image() helper to embed images in your templates. It supports loading from props, template directories, and URLs.
Prop-based Images
Pass the prop name to load an image path from props:
export const meta = {
name: "product-card",
type: "image",
size: { width: 1200, height: 630 },
props: {
title: "string",
background: "string?"
}
};
export default function ProductCard({ tw, image, title, background }) {
// Use fallback if no background prop provided
const bgSrc = background
? image('background')
: 'https://images.unsplash.com/photo-1557682250-33bd709cbe85?w=1200';
return (
<div style={tw('relative w-full h-full')}>
<img
src={bgSrc}
style={tw('absolute inset-0 w-full h-full object-cover')}
/>
<div style={tw('relative z-10 p-12')}>
<h1 style={tw('text-6xl font-bold text-white')}>{title}</h1>
</div>
</div>
);
}
The image('background') helper loads from the background prop value (file path or URL).
Direct File Images
Load images directly from your template directory by including the file extension:
export default function ChangelogItem({ tw, image, text }) {
return (
<div style={tw('flex items-center gap-4')}>
{/* Load check.svg from template directory */}
<img
src={image('check.svg')}
style={tw('w-6 h-6')}
/>
<span style={tw('text-lg')}>{text}</span>
</div>
);
}
You can also use subdirectories:
<img src={image('assets/icons/star.svg')} />
<img src={image('shared/logo.png')} />
Template directory structure:
.loopwind/my-template/
├── template.tsx
├── check.svg ← image('check.svg')
└── assets/
└── icons/
└── star.svg ← image('assets/icons/star.svg')
URLs
The image() helper also supports loading images from URLs:
{
"background": "https://example.com/image.jpg"
}
Supported Formats
- JPEG (
.jpg,.jpeg) - PNG (
.png) - GIF (
.gif) - WebP (
.webp) - SVG (
.svg)
Image Positioning
Use Tailwind’s object-fit utilities:
export default function ImageGrid({ tw, image, img1, img2, img3 }) {
return (
<div style={tw('flex gap-4 w-full h-full p-8 bg-gray-100')}>
{/* Cover - fills entire area, may crop */}
<img
src={image('img1')}
style={tw('w-full h-full object-cover rounded-lg')}
/>
{/* Contain - fits within area, may letterbox */}
<img
src={image('img2')}
style={tw('w-full h-full object-contain')}
/>
{/* Fill - stretches to fill */}
<img
src={image('img3')}
style={tw('w-full h-full object-fill')}
/>
</div>
);
}
Troubleshooting
Images Not Loading
Check file paths are relative to the props file:
{
"background": "./images/bg.jpg"
}
Absolute paths won’t work.
Optimize Image Sizes
Use appropriately sized images before embedding:
convert large-image.jpg -resize 1600x900 optimized.jpg