# Icons, Images & Photo Credits

## Icons, Images & Photo Credits

**Folder:** `src/assets/images/` · **Skill level:** Beginner

### Icons
Wherever a content or menu file has an `icon:` field (cause categories, badges, the "other ways to give" list, the donate fine print, partner marks), you can write any icon name from [Lucide](https://lucide.dev/icons/), a free set of more than 1,500 icons:

```yaml
icon: "HandHeart"
icon: "Droplets"
```

1. Find an icon on [lucide.dev/icons](https://lucide.dev/icons/).
2. Copy its name. `hand-heart` as written on the Lucide site works, and so does the PascalCase form `"HandHeart"`, which the theme files use.
3. Paste it as the `icon` value.

Every Lucide icon is drawn as inline SVG when the site is built (`src/lib/lucideIcons.ts`), so icons load with the page and follow the text color. A misspelled name draws no icon, so check new icons on the page.

An `icon` value that contains a `/` or a `.` is read as an image path instead, for example `icon: "/images/icons/my-badge.svg"` (a file in `src/assets/images/icons/`). Use it for your own SVG marks.

Arrows and chevrons point the other way on Arabic pages by themselves. See [RTL & Arabic](/givo/features/rtl-arabic/).

<Aside type="tip" title="For developers">
  In components, use `<DynamicIcon name="HandHeart" class="size-5" />`
  (`src/layouts/helpers/DynamicIcon.astro`), which takes a Lucide name or an
  image path, or `<Icons icon="HandHeart" />` (`src/layouts/helpers/Icons.astro`)
  for Lucide only. Adding a name to `src/lib/iconNames.ts` gives editor
  autocomplete; it is optional.
</Aside>

### Where Images Live
| Folder | What goes there | How to write the path |
| --- | --- | --- |
| `src/assets/images/photos/` | Every sample photo: causes, events, stories, heroes, the gallery, team portraits | `"/images/photos/cause-water-tap.jpg"` for `src/assets/images/photos/cause-water-tap.jpg` |
| `src/assets/images/partners/` | Partner logos (SVG) | `"/images/partners/your-logo.svg"` |
| `public/images/` | Files served as they are: favicons and the fallback social image `og-image.jpg` | `/images/og-image.jpg` |
| `public/videos/` | Self-hosted videos | `/videos/my-video.mp4` |

Images in `src/assets/images/` are optimized when the site is built: resized for each screen, converted to modern formats, and lazy-loaded. Always put your photos there unless a setting says `public/`.

The sample file names start with their use (`cause-`, `event-`, `story-`, `hero-`, `gallery-`, `team-`, `about-`, `volunteer-`). Most photos are 3:2 landscapes, a few are tall portraits, and the team portraits are 4:5. Keep the shape of a photo when you replace it, so the crop stays the same.

### Replace A Sample Photo
<Steps>

1. Put your photo in `src/assets/images/photos/` (or a folder of your own inside `src/assets/images/`), for example `src/assets/images/photos/our-well-2027.jpg`. A large JPG (about 2000 px wide) is fine: the build makes the smaller sizes.

2. In the content file that uses the old photo, change the path and describe the new photo:

   ```yaml
   image: "/images/photos/our-well-2027.jpg"
   imageAlt: "Villagers at the new hand pump on the day it opened"
   imageCaption: "Hill village · The third well on opening day · Photo: Your photographer"
   ```

3. Make the same change in each other language folder, with the alt text and caption in that language.

</Steps>

Or keep the file name and replace the file itself: every page that uses it changes at once.

To find which file uses a photo, search the project for its file name, for example `cause-water-tap.jpg`.

### Alt Text And Captions
Every photo field has a matching alt field, such as `imageAlt` or `alt`. Screen readers read it, and search engines use it.

- Describe what the photo shows, in one short sentence: "A boy pumping water at a village hand pump".
- Don't start with "Image of", and don't repeat the caption.
- Leave it empty (`""`) only for a purely decorative photo.

Many photos also have an `imageCaption`, shown under the photo: the place, what happens, and the photographer. The samples end with "Photo: sample credit" and are marked `# sample`. On `/gallery/`, `credit` at the top of `src/content/gallery/<language>/-index.md` is the default photographer, and an item's own `credit` replaces it. See [Partners & Gallery](/givo/customization/partners-gallery/).

### Dark Mode Images
A story's `image` can have a dark mode version in `imageDark`. In components, `OptimizedImage` takes `darkSrc` for the same purpose. Partner logos show in grayscale, so single-color SVG logos work best.

### Photo Rules For A Charity
- **Real people, with consent.** Photos of the people you help need their consent (or a parent's for a child). Avoid photos that show someone at their most vulnerable without their agreement.
- **No placeholder faces.** Team cards, supporter quotes, and the author box work without a photo: a team card without one shows a heart plate, and a quote or author box shows the name only. Add real portraits (4:5) with consent, or leave them out.
- **Your own work.** Photos of your programs, volunteers, and events build more trust than stock photos.

### Photo Credits And Licenses
`IMAGE-CREDITS.md` at the root of the theme lists every sample photo: its file, source, author, license, and the edits made. The sample photos come from Unsplash under the Unsplash License. It allows commercial use without attribution, but not selling or redistributing a photo on its own; keep them inside your site.

Replace the sample photos with your own before you launch. When you replace one, you can remove its row from `IMAGE-CREDITS.md`.

<Aside type="note">
  The wordmark and favicons are covered in [Site Identity & Logo](/givo/customization/site-identity-logo/).
  The social preview image is in [SEO & AI Visibility](/givo/customization/seo-ai-visibility/#social-preview-cards).
</Aside>

### Do It With AI
```text
I added my photos to src/assets/images/photos/: [LIST FILES AND WHAT EACH SHOWS]. Replace the
sample photos with them in the matching content files (every language): change the image path,
write a short, specific alt text in each language, and update imageCaption with the place and
photographer. Keep the shape of the photo you replace, and tell me which sample photos are still
in use.
```