| name | image-gallery |
| description | Use when you need to display and browse image collections. |
| metadata | {"id":"image-gallery","category":"media","pattern":"Image Gallery","source":"uxpatterns.dev","url":"https://uxpatterns.dev/patterns/media/image-gallery","sourcePath":"apps/web/content/patterns/media/image-gallery.mdx"} |
Image Gallery
Display and browse image collections
What it solves
A Image Gallery pattern helps teams create a reliable way to help users browse several related images without losing orientation, context, or performance. It is most useful when teams need portfolio and gallery pages.
Compared with adjacent patterns, this pattern should reduce friction without hiding the state, rules, or recovery paths people need to keep moving.
When to use
- Portfolio and gallery pages
- Product image collections
- Documentation screenshots and walkthroughs
When to avoid
- Use a simpler image, link, or file input if full media handling is not actually needed.
- Avoid rich custom controls when browser-native behavior is enough for the task.
- Do not assume network-heavy media is appropriate for every audience or context.
Implementation workflow
- Confirm the pattern matches the problem and constraints before copying the example.
- Start from the anatomy and examples in
references/pattern.md, then choose the smallest viable variation.
- Apply accessibility, performance, and interaction guardrails before layering visual polish.
- Use the testing guidance to verify behavior across keyboard, screen reader, responsive, and failure scenarios.
Accessibility guardrails
