1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
---
order: 1
title: Intersect
description: An Alpine convenience wrapper for Intersection Observer that allows you to easily react when an element enters the viewport.
graph_image: https://alpinejs.dev/social_intersect.jpg
---
# Intersect Plugin
Alpine's Intersect plugin is a convenience wrapper for [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) that allows you to easily react when an element enters the viewport.
This is useful for: lazy loading images and other content, triggering animations, infinite scrolling, logging "views" of content, etc.
<a name="installation"></a>
## Installation
You can use this plugin by either including it from a `<script>` tag or installing it via NPM:
### Via CDN
You can include the CDN build of this plugin as a `<script>` tag, just make sure to include it BEFORE Alpine's core JS file.
```alpine
<!-- Alpine Plugins -->
<script defer src="https://unpkg.com/@alpinejs/intersect@3.x.x/dist/cdn.min.js"></script>
<!-- Alpine Core -->
<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
```
### Via NPM
You can install Intersect from NPM for use inside your bundle like so:
```shell
npm install @alpinejs/intersect
```
Then initialize it from your bundle:
```js
import Alpine from 'alpinejs'
import intersect from '@alpinejs/intersect'
Alpine.plugin(intersect)
...
```
<a name="x-intersect"></a>
## x-intersect
The primary API for using this plugin is `x-intersect`. You can add `x-intersect` to any element within an Alpine component, and when that component enters the viewport (is scrolled into view), the provided expression will execute.
For example, in the following snippet, `shown` will remain `false` until the element is scrolled into view. At that point, the expression will execute and `shown` will become `true`:
```alpine
<div x-data="{ shown: false }" x-intersect="shown = true">
<div x-show="shown" x-transition>
I'm in the viewport!
</div>
</div>
```
<!-- START_VERBATIM -->
<div class="demo" style="height: 60px; overflow-y: scroll;" x-data x-ref="root">
<a href="#" @click.prevent="$refs.root.scrollTo({ top: $refs.root.scrollHeight, behavior: 'smooth' })">Scroll Down 👇</a>
<div style="height: 50vh"></div>
<div x-data="{ shown: false }" x-intersect="shown = true" id="yoyo">
<div x-show="shown" x-transition.duration.1000ms>
I'm in the viewport!
</div>
<div x-show="! shown"> </div>
</div>
</div>
<!-- END_VERBATIM -->
<a name="x-intersect-enter"></a>
### x-intersect:enter
The `:enter` suffix is an alias of `x-intersect`, and works the same way:
```alpine
<div x-intersect:enter="shown = true">...</div>
```
You may choose to use this for clarity when also using the `:leave` suffix.
<a name="x-intersect-leave"></a>
### x-intersect:leave
Appending `:leave` runs your expression when the element leaves the viewport:
```alpine
<div x-intersect:leave="shown = true">...</div>
```
<a name="modifiers"></a>
## Modifiers
<a name="once"></a>
### .once
Sometimes it's useful to evaluate an expression only the first time an element enters the viewport and not subsequent times. For example when triggering "enter" animations. In these cases, you can add the `.once` modifier to `x-intersect` to achieve this.
```alpine
<div x-intersect.once="shown = true">...</div>
```
<a name="half"></a>
### .half
Evaluates the expression once the intersection threshold exceeds `0.5`.
Useful for elements where it's important to show at least part of the element.
```alpine
<div x-intersect.half="shown = true">...</div> // when `0.5` of the element is in the viewport
```
<a name="full"></a>
### .full
Evaluates the expression once the intersection threshold exceeds `0.99`.
Useful for elements where it's important to show the whole element.
```alpine
<div x-intersect.full="shown = true">...</div> // when `0.99` of the element is in the viewport
```
<a name="margin"></a>
### .margin
Allows you to control the `rootMargin` property of the underlying `IntersectionObserver`.
This effectively tweaks the size of the viewport boundary. Positive values
expand the boundary beyond the viewport, and negative values shrink it inward. The values
work like CSS margin: one value for all sides, two values for top/bottom, left/right, or
four values for top, right, bottom, left. You can use `px` and `%` values, or use a bare number to
get a pixel value.
```alpine
<div x-intersect.margin.200px="loaded = true">...</div> // Load when the element is within 200px of the viewport
```
```alpine
<div x-intersect:leave.margin.10%.25px.25.25px="loaded = false">...</div> // Unload when the element gets within 10% of the top of the viewport, or within 25px of the other three edges
```
```alpine
<div x-intersect.margin.-100px="visible = true">...</div> // Mark as visible when element is more than 100 pixels into the viewport.
```
|
