Selection And Input
Image Wells
An Image View frame with an empty-state affordance — the same ratio-locked container, showing an upload icon instead of a shimmer until a value exists.
Findings
What's actually in /ig
- An Image Well extends the standard ratio-locked Image View frame with one additional empty state for choosing media.
Rationale
Why this component exists
An image well doesn't need new anatomy: it's the Image View's ratio frame, holding either a placeholder icon (empty) or the chosen media (filled), with the same shimmer transition between states that every loading image in the system already uses.
Usage
When to use it
Use when
Letting a user choose or replace a single image value — a profile photo, a cover image.
Avoid when
Multiple images are being chosen at once (use Collections) or no replace/clear action is needed (use a plain Image View).
Anatomy
Anatomy
- 01
Ratio frame (Image View anatomy)
- 02
Empty-state icon
- 03
Filled state (chosen media)
- 04
Replace/clear affordance
Specification
Spacing, colour, type, and motion
- Frame
- Same aspect-ratio + object-fit: cover as Image Views
- Empty fill
- rgb(var(--ig-secondary-background)) with a centered icon at rgb(var(--ig-tertiary-text))
- Border
- 1px dashed rgb(var(--ig-separator)) in the empty state only
States
States
| State | Behaviour |
|---|---|
| Default | Empty well shows the ratio frame with secondary fill, centered icon, and dashed separator border. |
| Hover | The frame receives rgba(var(--ig-hover-overlay-rgb), var(--ig-hover-overlay-alpha)) to indicate the choose or replace target. |
| Pressed/Active | The frame uses an overlay slightly deeper than hover overlay while the media action is pressed. |
| Focused | The focused frame uses a 2px var(--ig-stop-magenta) outline with a --radius-xs offset. |
| Filled | Chosen media fills the frame with the same aspect-ratio and object-fit: cover rules as Image Views. |
| Loading | A shimmer skeleton covers the frame while the chosen media resolves into the filled state. |
| Disabled | Disabled wells have opacity reduced and pointer-events none while the placeholder or chosen media remains visible. |
Examples
Real interface compositions
Edit profile
Profile photo picker
An empty circular frame shows a neutral camera affordance; once a photo is chosen, the same Image View crop rules take over with replace and clear actions nearby.
Image View ratio rules, --ig-secondary-background empty fill, dashed --ig-separator border
Do / Don't
Do / Don't
Do
- Reuse the exact ratio and object-fit rules from Image Views — don't introduce a second cropping convention for the well state.
Don’t
- Show a generic file-upload icon unrelated to the system's iconography — keep it visually consistent with the rest of the icon set.
See also