> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kleap.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Using Images
> Best practices for images in your app
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 `` component, or plain `` 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 `` 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 `` component from `astro:assets`. Put the source in `src/assets/` and import it:
```astro theme={null}
---
import { Image } from 'astro:assets';
import hero from '../assets/hero.jpg';
---
```
### 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 `` works too — just add `width`, `height`, and `loading="lazy"`:
```html theme={null}
```
For a hero image (usually your largest, above-the-fold visual), load it eagerly so it appears fast:
```html theme={null}
```
### Ask AI to Optimize
```
"Optimize all images: use Astro's 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:
```astro theme={null}
```
## Responsive Images
### Cover a Container
To fill a container while keeping aspect ratio, size the wrapper and use `object-cover`:
```html theme={null}
```
### Responsive Sizes
Tell the browser what size to load:
```astro theme={null}
```
## External Images
For images hosted elsewhere (Unsplash, a CDN, your own server), just reference the URL with a plain ``:
```html theme={null}
```
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:
```html theme={null}
```
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:
```html theme={null}
Content here
```
### With Overlay
```html theme={null}
Content here
```
## Icons
### Lucide Icons
Kleap uses Lucide icons via `lucide-react`, rendered inside React islands:
```tsx theme={null}
import { Home, Settings, User } from 'lucide-react';
```
### SVG Icons
For custom icons:
```html theme={null}
```
## Alt Text Guidelines
Always provide descriptive alt text:
```html theme={null}
```
### When to Use Empty Alt
Decorative images that don't convey information:
```html theme={null}
```
## 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
* Check the file path is correct
* Verify the image exists in the public folder
* For external images, confirm the URL is public and reachable
* Provide a higher resolution source image
* Check width/height props match the aspect ratio
* Prefer Astro's `` so the right size is served
* Always specify width and height
* Use Astro's ``, which reserves space automatically
* Wrap in a sized container for cover/fill layouts
Learn how to embed videos in your app
```
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:
```html theme={null}
```
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:
```html theme={null}
```
## 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