# Image Clip Reveal
> A cinematic image reveal where a directional polygon aperture opens as the photograph settles from a restrained Ken Burns scale and its editorial caption lands.
Canonical: https://gsapvault.com/effects/image-clip-reveal
Live demo: https://gsapvault.com/demos/image-clip-reveal/index.html
| Property | Value |
|----------|-------|
| Type | effect |
| Tier | free |
| Price | Free |
| Difficulty | beginner |
| Plugins | ScrollTrigger |
| Techniques | scroll-reveal, clip-path, ken-burns, stagger |
| Uses Lenis | Yes |
## Overview
A cinematic image reveal effect that opens photographs through a directional polygon aperture while GSAP settles the inner image from a restrained scale. Optional caption, rule, and atmosphere hooks extend the same timeline into a complete editorial entrance without changing the core image API. Direction, duration, delay, replay behaviour, and staggered groups remain configurable through data attributes.
## Features
- Architectural polygon aperture with four directional reveal options
- Restrained inner-image scale settle synchronized with the mask
- Optional editorial caption, rule, and atmosphere timeline hooks
- Per-image direction, duration, delay, and replay data attributes
- Stagger groups preserved for sequencing multiple image wrappers
- Semantic replay control and a small programmatic replay API
- No-JavaScript fallback that shows the full image and caption
- Reduced-motion branch with no clipping, scale, or ScrollTrigger
## Use Cases
- Architecture portfolios with a precise editorial image entrance
- Travel stories with cinematic location photography and captions
- Case-study heroes that need one composed visual reveal
- Magazine layouts with directional image wipes and metadata
- Campaign landing pages with restrained, replayable photography
## Vibe-Code Ready Setup
This effect includes `START-HERE-AI.md`, a product-specific copy-paste setup prompt for Cursor, Claude Code, ChatGPT, GitHub Copilot, Windsurf, and other coding assistants. It tells the assistant to inspect the existing stack, integrate the supplied files, preserve the design, scope selectors, retain accessibility and responsive behaviour, add framework-appropriate GSAP cleanup, and report what it tested.
[How AI-assisted setup works](https://gsapvault.com/vibe-coding)
## How It Works
Each data-clip-reveal wrapper receives a GSAP timeline and ScrollTrigger. The wrapper's six-point clip-path interpolates from a narrow directional wedge to the full frame while its inner image scales from 1.14 to 1; optional atmosphere, rule, and caption targets enter just after the image becomes legible. Data attributes preserve direction, duration, delay, once/replay, and group stagger controls, while window.imageClipReveal exposes replay() and destroy() methods. A gsap.matchMedia() reduced-motion branch clears all animated states, and initial hidden styles are gated by a head-added has-js class so the no-JavaScript fallback remains complete.
## Documentation
A directional polygon aperture opens while the inner photograph settles from a restrained scale. Optional atmosphere, rule, and caption hooks turn the image wipe into a complete editorial entrance.
## Quick Start
**1. Add to your HTML ``:**
```html
```
The small `has-js` gate is important: animated elements are hidden only when JavaScript is available, so the full image and caption remain visible without JavaScript.
**2. Add to your ``:**
```html
Ottawa, CanadaConstitution Square
```
`data-reveal-caption`, `data-reveal-rule`, and `data-reveal-copy` are optional. The image reveal works without caption markup.
**3. Add before the closing `` tag:**
```html
```
## Options
All image options are data attributes on the `data-clip-reveal` wrapper:
| Attribute | Values | Default | Description |
|---|---|---|---|
| `data-reveal-direction` | `up`, `down`, `left`, `right` | `up` | Edge and travel direction of the polygon aperture |
| `data-reveal-duration` | Seconds | `1.1` | Duration of the clip-path wipe; the image settle runs slightly longer |
| `data-reveal-delay` | Seconds | `0` | Delay before the reveal begins |
| `data-reveal-once` | `true`, `false` | `true` | Play once, or reset and replay when the trigger re-enters |
Optional descendant hooks:
| Attribute | Element | Description |
|---|---|---|
| `data-reveal-atmosphere` | Element inside the closest `figure` | Fades and scales subtle ambient color with the image |
| `data-reveal-caption` | `figcaption` inside the closest `figure` | Locates caption animation targets |
| `data-reveal-rule` | Element inside the caption | Scales a rule in shortly after the image |
| `data-reveal-copy` | Elements inside the caption | Reveals caption lines with a short stagger |
| `data-clip-replay` | `button` | Semantically replays every active reveal timeline |
## Examples
### Direction, Duration, and Replay
**Add to your HTML ``:**
```html
```
Direction names retain the original API. `right` grows from the left edge toward the right, `left` grows from the right edge, `up` grows from the bottom, and `down` grows from the top.
### Staggered Group
The group API remains available when a project needs multiple images, even though the included demo intentionally uses one cinematic composition.
**Add to your HTML ``:**
```html
```
| Group Attribute | Values | Default | Description |
|---|---|---|---|
| `data-clip-reveal-group` | Presence | n/a | Builds one ScrollTrigger timeline for all child reveals |
| `data-reveal-stagger` | Seconds | `0.12` | Timeline offset between child reveals |
Direction, duration, delay, and once/replay attributes on the group become defaults. A child's own values override them.
## Styling Notes
The supplied demo CSS is intentionally editorial. For integration, preserve these functional rules while adapting the visual design:
- `overflow: hidden` on `[data-clip-reveal]`
- matching six-point closed polygon states under `.has-js`
- the `transform: scale(1.14)` image start state under `.has-js`
- overflow masks around any `data-reveal-copy` elements
- reduced-motion overrides that clear clip, scale, opacity, and translation
The open and closed polygon strings use the same number of points, which keeps browser interpolation stable.
## How It Works
Each standalone wrapper gets a timeline triggered at `top 85%`. GSAP interpolates the wrapper from a narrow directional six-point polygon to the full frame while scaling the inner image from `1.14` to `1`. The optional atmosphere begins with the image; the caption rule and copy enter at 72% of the configured reveal duration, giving the photograph time to become legible first.
With `data-reveal-once="false"`, ScrollTrigger uses `toggleActions: 'restart none none reset'`. Group wrappers share one timeline and offset child reveals by `data-reveal-stagger`.
## Programmatic API
**Add to your JavaScript after the effect has initialized:**
```javascript
// Replay every active reveal timeline.
window.imageClipReveal.replay();
// Kill timelines, ScrollTriggers, listeners, context, and Lenis integration.
window.imageClipReveal.destroy();
// The original GSAP context handle remains available.
window.gsapContext.revert();
```
## Accessibility
- The full image, rule, and caption are visible when JavaScript is unavailable.
- CSS and `gsap.matchMedia()` both honor `prefers-reduced-motion`; no ScrollTrigger is created in the reduced branch.
- The replay control is a native button with a visible keyboard focus state.
- Keep meaningful image descriptions in `alt`; decorative atmosphere and rules should use `aria-hidden="true"`.
- The effect is scroll-triggered and does not require a pointer.
## Dependencies
**Required:**
- GSAP 3.12+
- ScrollTrigger
**Optional:**
- Lenis for smooth scrolling. The included integration is disabled by `data-smooth="off"`, `?smooth=off`, or reduced-motion preference, and the effect works without Lenis.
## Source Code
This effect is free. The complete source is included below.
### index.html
```html
Image Clip Reveal Demo | GSAP Vault
Directional apertureImage and caption settle in sequence
