Using Images - Kleap Documentation

Learn how to effectively use images in your Kleap app. Kleap builds Astro static sites, so images use standard web patterns — files in your public/ folder, Astro’s optimized <Image /> component, or plain <img> tags. There’s no image build configuration to set up.

Adding Images

From URL

Use any public image URL:

"Add a hero image using this URL: https://example.com/hero.jpg"

External images work with a normal <img> tag — no allowlist or domain configuration required.

Uploading Images

Upload images directly in Kleap and the AI will place them for you:

"Add an image to the about page." (then attach or upload your image)

Uploaded images are hosted by Kleap and stored in your app’s public/ folder, accessible at /image-name.jpg.

Generate Images with AI

Kleap can generate images for you with AI — free, no credits used:

"Generate a hero image of a modern office workspace for the homepage."

Great for hero backgrounds, illustrations, and placeholders when you don’t have your own photos yet.

Astro Image Component

For images you ship with your site, use Astro’s built-in <Image /> component from astro:assets. Put the source in src/assets/ and import it:

---
import { Image } from 'astro:assets';
import hero from '../assets/hero.jpg';
---

<Image src={hero} alt="Hero image" width={1200} height={600} />

Benefits

Automatic optimization - Converts to WebP/AVIF
Lazy loading - loading="lazy" by default
Correct sizing - Serves an appropriately sized image
No layout shift - Requires width/height, which prevents CLS

Plain img tags

For images in public/ (including uploaded and AI-generated ones), a normal <img> works too — just add width, height, and loading="lazy":

<img src="/hero.jpg" alt="Hero image" width="1200" height="600" loading="lazy" />

For a hero image (usually your largest, above-the-fold visual), load it eagerly so it appears fast:

<img src="/hero.jpg" alt="Hero" width="1600" height="900" loading="eager" fetchpriority="high" />

Ask AI to Optimize

"Optimize all images: use Astro's <Image /> where possible, add
correct width and height, lazy loading, and descriptive alt text."

Image Best Practices

File Formats

Format	Best For
WebP	Photos, general use
PNG	Logos, icons, transparency
SVG	Icons, illustrations
AVIF	Best compression (newer)

File Sizes

Keep images optimized:

Hero images: < 200KB
Content images: < 100KB
Thumbnails: < 30KB

Dimensions

Provide images at appropriate sizes. For responsive images, tell the browser which size to load with the widths and sizes props:

<Image
  src={product}
  alt="Product"
  widths={[400, 800, 1200]}
  sizes="(max-width: 768px) 100vw, 50vw"
/>

Responsive Images

Cover a Container

To fill a container while keeping aspect ratio, size the wrapper and use object-cover:

<div class="relative w-full h-64">
  <img
    src="/hero.jpg"
    alt="Hero"
    class="absolute inset-0 w-full h-full object-cover"
  />
</div>

Responsive Sizes

Tell the browser what size to load:

<Image
  src={photo}
  alt="Photo"
  widths={[640, 1024, 1280]}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
/>

External Images

For images hosted elsewhere (Unsplash, a CDN, your own server), just reference the URL with a plain <img>:

<img
  src="https://images.unsplash.com/photo-123"
  alt="Team collaborating"
  loading="lazy"
/>

No domain allowlist or config is needed — Astro sites serve external image URLs directly. Popular sources include:

images.unsplash.com
cdn.pixabay.com
res.cloudinary.com

Uploaded & Generated Images

Most images on a Kleap site are static assets — files you upload in Kleap or generate with AI. These are hosted by Kleap in your public/ folder, so you reference them like any local image:

<img
  src="/team-photo.jpg"
  alt="Our team at the office"
  width="800"
  height="600"
  loading="lazy"
/>

If you need to accept image uploads from your own visitors at runtime, store them in Kleap Database and render them from the stored URL. For most sites, static uploaded or AI-generated assets are all you need.

Background Images

CSS Background

For decorative backgrounds:

<div class="bg-cover bg-center h-96" style="background-image: url(/pattern.svg)">
  Content here
</div>

With Overlay

<div class="relative h-96">
  <img src="/hero.jpg" alt="" class="absolute inset-0 w-full h-full object-cover" />
  <div class="absolute inset-0 bg-black/50"></div>
  <div class="relative z-10 text-white">
    Content here
  </div>
</div>

Icons

Lucide Icons

Kleap uses Lucide icons via lucide-react, rendered inside React islands:

import { Home, Settings, User } from 'lucide-react';

<Home className="w-6 h-6" />

SVG Icons

For custom icons:

<svg class="w-6 h-6" viewBox="0 0 24 24">
  <!-- SVG paths -->
</svg>

Alt Text Guidelines

Always provide descriptive alt text:

<!-- ❌ Bad -->
<img src="/team.jpg" alt="image" />
<img src="/team.jpg" alt="" />

<!-- ✅ Good -->
<img src="/team.jpg" alt="Our team of five developers at the office" />

When to Use Empty Alt

Decorative images that don’t convey information:

<img src="/decoration.svg" alt="" role="presentation" />

Common Image Patterns

Hero with Image

"Create a hero section with a large background image,
overlay, and centered text content"

Image Gallery

"Add an image gallery with a grid layout that opens
images in a lightbox when clicked"

Avatar

"Add user avatars to the comments section using each
person's profile image"

Troubleshooting

Image not loading

Check the file path is correct
Verify the image exists in the public folder
For external images, confirm the URL is public and reachable

Image looks blurry

Provide a higher resolution source image
Check width/height props match the aspect ratio
Prefer Astro’s <Image /> so the right size is served

Layout shift when loading

Always specify width and height
Use Astro’s <Image />, which reserves space automatically
Wrap in a sized container for cover/fill layouts

Using Videos

Learn how to embed videos in your app

​Adding Images

​From URL

​Uploading Images

​Generate Images with AI

​Astro Image Component

​Benefits

​Plain img tags

​Ask AI to Optimize

​Image Best Practices

​File Formats

​File Sizes

​Dimensions

​Responsive Images

​Cover a Container

​Responsive Sizes

​External Images

​Uploaded & Generated Images

​Background Images

​CSS Background

​With Overlay

​Icons

​Lucide Icons

​SVG Icons

​Alt Text Guidelines

​When to Use Empty Alt

​Common Image Patterns

​Hero with Image

​Image Gallery

​Avatar

​Troubleshooting