| 1 |
# Reveal Swipe Cards Widget – Developer Guide |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
The **Reveal Swipe Cards** widget creates a responsive card grid where each card's content is initially hidden behind a colored overlay. When the user hovers over (or scrolls into view), the overlay "wipes" away in a specified direction to reveal the card's content. |
| 6 |
|
| 7 |
**Free version** supports hover/scroll triggers, 4-direction wipe, and full style customization. |
| 8 |
**Pro version** adds mask shapes (circle, diagonal, wave), blur edge effect, touch swipe reveal, click trigger, and sequence modes (stagger, active-one). |
| 9 |
|
| 10 |
--- |
| 11 |
|
| 12 |
## File Structure |
| 13 |
|
| 14 |
``` |
| 15 |
king-addons/ |
| 16 |
└── includes/ |
| 17 |
└── widgets/ |
| 18 |
└── Reveal_Swipe_Cards/ |
| 19 |
├── Reveal_Swipe_Cards.php # Free widget class |
| 20 |
├── script.js # Frontend JavaScript |
| 21 |
└── style.css # Base + Pro styles |
| 22 |
|
| 23 |
king-addons-pro/ |
| 24 |
└── includes/ |
| 25 |
└── widgets/ |
| 26 |
└── Reveal_Swipe_Cards_Pro/ |
| 27 |
└── Reveal_Swipe_Cards_Pro.php # Pro widget class (extends Free) |
| 28 |
``` |
| 29 |
|
| 30 |
--- |
| 31 |
|
| 32 |
## CSS Custom Properties (Design Tokens) |
| 33 |
|
| 34 |
All major values are exposed via CSS custom properties for easy theming: |
| 35 |
|
| 36 |
| Property | Default | Description | |
| 37 |
|-----------------------------|---------------|--------------------------------------| |
| 38 |
| `--kng-rsc-columns` | `3` | Grid column count | |
| 39 |
| `--kng-rsc-gap` | `24px` | Gap between cards | |
| 40 |
| `--kng-rsc-min-height` | `320px` | Minimum card height | |
| 41 |
| `--kng-rsc-content-align` | `center` | Vertical content alignment | |
| 42 |
| `--kng-rsc-text-align` | `center` | Horizontal text alignment | |
| 43 |
| `--kng-rsc-duration` | `500ms` | Reveal animation duration | |
| 44 |
| `--kng-rsc-easing` | `ease-out` | CSS easing function | |
| 45 |
| `--kng-rsc-overlay-color` | `#2563eb` | Overlay background color | |
| 46 |
| `--kng-rsc-overlay-opacity` | `1` | Overlay opacity | |
| 47 |
| `--kng-rsc-blur-edge` | `0px` | Blur edge softness (Pro) | |
| 48 |
| `--kng-rsc-mask-shape` | `rect` | Mask shape identifier | |
| 49 |
|
| 50 |
--- |
| 51 |
|
| 52 |
## HTML Structure |
| 53 |
|
| 54 |
```html |
| 55 |
<div class="kng-rsc" data-settings="{...}"> |
| 56 |
<div class="kng-rsc__grid" role="list"> |
| 57 |
|
| 58 |
<div class="kng-rsc-card kng-rsc-card--direction-left" data-index="0"> |
| 59 |
<!-- Optional badge --> |
| 60 |
<span class="kng-rsc-card__badge kng-rsc-card__badge--top-right">New</span> |
| 61 |
|
| 62 |
<div class="kng-rsc-card__content"> |
| 63 |
<div class="kng-rsc-card__inner"> |
| 64 |
<div class="kng-rsc-card__media"> |
| 65 |
<span class="kng-rsc-card__icon">...</span> |
| 66 |
</div> |
| 67 |
<h3 class="kng-rsc-card__title">Card Title</h3> |
| 68 |
<p class="kng-rsc-card__description">Card description text.</p> |
| 69 |
<a href="#" class="kng-rsc-card__button">Learn More</a> |
| 70 |
</div> |
| 71 |
</div> |
| 72 |
|
| 73 |
<div class="kng-rsc-card__overlay" aria-hidden="true"></div> |
| 74 |
</div> |
| 75 |
|
| 76 |
<!-- More cards... --> |
| 77 |
</div> |
| 78 |
</div> |
| 79 |
``` |
| 80 |
|
| 81 |
--- |
| 82 |
|
| 83 |
## JavaScript API |
| 84 |
|
| 85 |
### Data Settings (passed via `data-settings` attribute) |
| 86 |
|
| 87 |
```js |
| 88 |
{ |
| 89 |
trigger: "hover" | "scroll" | "both" | "click", |
| 90 |
direction: "left" | "right" | "top" | "bottom", |
| 91 |
duration: 500, // ms |
| 92 |
easing: "ease-out", |
| 93 |
resetOnLeave: true, |
| 94 |
scroll: { |
| 95 |
threshold: 0.3, // 0-1, viewport intersection ratio |
| 96 |
once: false, // reveal only once |
| 97 |
resetOnExit: false // reset when leaving viewport |
| 98 |
}, |
| 99 |
// Pro options: |
| 100 |
maskShape: "rect" | "circle" | "rounded" | "diagonal" | "wave", |
| 101 |
blurEdge: { |
| 102 |
enable: false, |
| 103 |
softness: 20 |
| 104 |
}, |
| 105 |
touch: { |
| 106 |
enable: false, |
| 107 |
threshold: 50, // px |
| 108 |
velocity: 0.5, // px/ms |
| 109 |
directionLock: true |
| 110 |
}, |
| 111 |
sequence: { |
| 112 |
mode: "off" | "stagger" | "active-one", |
| 113 |
delay: 100 // ms between cards in stagger mode |
| 114 |
} |
| 115 |
} |
| 116 |
``` |
| 117 |
|
| 118 |
### Events |
| 119 |
|
| 120 |
The widget dispatches custom events on the wrapper element: |
| 121 |
|
| 122 |
| Event | Detail | Description | |
| 123 |
|--------------------------|---------------------------------|--------------------------------| |
| 124 |
| `kng-rsc:reveal` | `{ index, card }` | Card reveal started | |
| 125 |
| `kng-rsc:hide` | `{ index, card }` | Card hide started | |
| 126 |
| `kng-rsc:reveal-complete`| `{ index, card }` | Card reveal animation complete | |
| 127 |
|
| 128 |
### State Classes |
| 129 |
|
| 130 |
| Class | Applied To | Description | |
| 131 |
|-----------------|----------------|-----------------------------------| |
| 132 |
| `.is-revealed` | `.kng-rsc-card`| Card overlay is animated away | |
| 133 |
| `.is-dragging` | `.kng-rsc-card`| Touch swipe in progress (Pro) | |
| 134 |
| `.is-instant` | `.kng-rsc-card`| No animation (reduced motion) | |
| 135 |
|
| 136 |
--- |
| 137 |
|
| 138 |
## Reveal Directions |
| 139 |
|
| 140 |
The overlay slides in the opposite direction of the setting name: |
| 141 |
|
| 142 |
| Setting | Overlay Slides | Visual Result | |
| 143 |
|------------|----------------|-----------------------------| |
| 144 |
| `left` | Left → Right | Content revealed from left | |
| 145 |
| `right` | Right → Left | Content revealed from right | |
| 146 |
| `top` | Top → Bottom | Content revealed from top | |
| 147 |
| `bottom` | Bottom → Top | Content revealed from bottom| |
| 148 |
|
| 149 |
--- |
| 150 |
|
| 151 |
## Pro Features |
| 152 |
|
| 153 |
### Mask Shapes |
| 154 |
|
| 155 |
Instead of a linear wipe, Pro offers creative reveal shapes: |
| 156 |
|
| 157 |
- **circle**: Circular shrink from center outward (uses `clip-path: circle()`) |
| 158 |
- **rounded**: Rectangle with increasing border-radius |
| 159 |
- **diagonal**: Diagonal wipe using `clip-path: polygon()` |
| 160 |
- **wave**: Wavy edge wipe (CSS polygon) |
| 161 |
|
| 162 |
### Blur Edge Effect |
| 163 |
|
| 164 |
Adds a soft gradient edge to the overlay as it reveals, creating a smoother transition. Only works with `rect` mask shape. |
| 165 |
|
| 166 |
### Touch Swipe |
| 167 |
|
| 168 |
On touch devices, users can swipe to reveal cards: |
| 169 |
- **Threshold**: Minimum swipe distance before trigger |
| 170 |
- **Velocity**: Minimum swipe speed (pixels/ms) |
| 171 |
- **Direction Lock**: Only allow swipe in the reveal direction |
| 172 |
|
| 173 |
### Sequence Modes |
| 174 |
|
| 175 |
- **Stagger**: When triggered (e.g., scroll into view), cards reveal one after another with a configurable delay |
| 176 |
- **Active One**: Only one card can be revealed at a time; revealing a new card hides the previous one |
| 177 |
|
| 178 |
### Click Trigger |
| 179 |
|
| 180 |
Cards can be revealed/hidden by clicking/tapping instead of hovering. |
| 181 |
|
| 182 |
--- |
| 183 |
|
| 184 |
## Accessibility |
| 185 |
|
| 186 |
1. **Reduced Motion**: Widget respects `prefers-reduced-motion` and disables animations when set |
| 187 |
2. **Keyboard Support**: Cards can be focused and triggered via keyboard (focus = reveal) |
| 188 |
3. **ARIA**: Overlay has `aria-hidden="true"` since it's decorative |
| 189 |
4. **Focus Visible**: Button and card have visible focus outlines |
| 190 |
|
| 191 |
--- |
| 192 |
|
| 193 |
## Performance Considerations |
| 194 |
|
| 195 |
1. **GPU-Accelerated**: Uses `transform` and `clip-path` for animations (no layout thrashing) |
| 196 |
2. **will-change**: Applied sparingly to `.kng-rsc-card__overlay` |
| 197 |
3. **Intersection Observer**: Used for scroll triggers (no scroll listeners) |
| 198 |
4. **Event Delegation**: Uses delegated event listeners where possible |
| 199 |
|
| 200 |
--- |
| 201 |
|
| 202 |
## Customization Examples |
| 203 |
|
| 204 |
### Custom Overlay Gradient (CSS) |
| 205 |
|
| 206 |
```css |
| 207 |
.kng-rsc-card__overlay { |
| 208 |
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); |
| 209 |
} |
| 210 |
``` |
| 211 |
|
| 212 |
### Slower Animation |
| 213 |
|
| 214 |
```css |
| 215 |
.kng-rsc { |
| 216 |
--kng-rsc-duration: 800ms; |
| 217 |
--kng-rsc-easing: cubic-bezier(0.4, 0, 0.2, 1); |
| 218 |
} |
| 219 |
``` |
| 220 |
|
| 221 |
### Hook into Reveal Event (JavaScript) |
| 222 |
|
| 223 |
```js |
| 224 |
document.querySelector('.kng-rsc').addEventListener('kng-rsc:reveal', (e) => { |
| 225 |
console.log('Card revealed:', e.detail.index); |
| 226 |
}); |
| 227 |
``` |
| 228 |
|
| 229 |
--- |
| 230 |
|
| 231 |
## Troubleshooting |
| 232 |
|
| 233 |
| Issue | Solution | |
| 234 |
|--------------------------------|----------------------------------------------------| |
| 235 |
| Overlay not animating | Check if reduced motion is enabled on device | |
| 236 |
| Cards not revealing on scroll | Ensure `trigger` includes `scroll` | |
| 237 |
| Touch swipe not working | Enable touch in Pro settings, check threshold | |
| 238 |
| Overlay color not changing | Use Elementor style controls or override CSS var | |
| 239 |
| Badge hidden behind overlay | Badge has `z-index: 3`, should be above overlay | |
| 240 |
|
| 241 |
--- |
| 242 |
|
| 243 |
## Changelog |
| 244 |
|
| 245 |
### 1.0.0 |
| 246 |
- Initial release with hover/scroll triggers |
| 247 |
- 4-direction reveal animation |
| 248 |
- Responsive grid layout |
| 249 |
- Badge support |
| 250 |
- Full style controls |
| 251 |
|
| 252 |
### 1.0.0 Pro |
| 253 |
- Mask shapes (circle, diagonal, wave) |
| 254 |
- Blur edge effect |
| 255 |
- Touch swipe reveal |
| 256 |
- Click trigger |
| 257 |
- Sequence modes (stagger, active-one) |
| 258 |
- Gradient overlay support |
| 259 |
- Box shadow controls |
| 260 |
|
