Skip to content

Commit 3d2c262

Browse files
thebuilderthebuilder
committed
docs: add stackblitz button
1 parent b0205ee commit 3d2c262

File tree

1 file changed

+48
-63
lines changed

1 file changed

+48
-63
lines changed

‎README.md

+48-63
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ to tell you when an element enters or leaves the viewport. Contains both a
1212
[Hooks](#useinview-hook), [render props](#render-props) and
1313
[plain children](#plain-children) implementation.
1414

15-
1615
## Features
1716

1817
- 🪝 **Hooks or Component API** - With `useInView` it's easier than ever to
@@ -28,6 +27,8 @@ to tell you when an element enters or leaves the viewport. Contains both a
2827
- 💥 **Tiny bundle** - Around **~1.15kB** for `useInView` and **~1.6kB** for
2928
`<InView>`
3029

30+
[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/thebuilder/react-intersection-observer)
31+
3132
## Installation
3233

3334
Install the package with your package manager of choice:
@@ -57,8 +58,8 @@ Assign the `ref` to the DOM element you want to monitor, and the hook will
5758
report the status.
5859

5960
```jsx
60-
import React from 'react';
61-
import { useInView } from 'react-intersection-observer';
61+
import React from "react";
62+
import { useInView } from "react-intersection-observer";
6263

6364
const Component = () => {
6465
const { ref, inView, entry } = useInView({
@@ -88,7 +89,7 @@ on `entry`, giving you access to all the details about the current intersection
8889
state.
8990

9091
```jsx
91-
import { InView } from 'react-intersection-observer';
92+
import { InView } from "react-intersection-observer";
9293

9394
const Component = () => (
9495
<InView>
@@ -111,10 +112,10 @@ state in your own component. Any extra props you add to `<InView>` will be
111112
passed to the HTML element, allowing you set the `className`, `style`, etc.
112113

113114
```jsx
114-
import { InView } from 'react-intersection-observer';
115+
import { InView } from "react-intersection-observer";
115116

116117
const Component = () => (
117-
<InView as="div" onChange={(inView, entry) => console.log('Inview:', inView)}>
118+
<InView as="div" onChange={(inView, entry) => console.log("Inview:", inView)}>
118119
<h2>Plain children are always rendered. Use onChange to monitor state.</h2>
119120
</InView>
120121
);
@@ -135,7 +136,7 @@ Provide these as the options argument in the `useInView` hook or as props on the
135136
**`<InView />`** component.
136137

137138
| Name | Type | Default | Description |
138-
|------------------------|---------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
139+
| ---------------------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139140
| **root** | `Element` | `document` | The Intersection Observer interface's read-only root property identifies the Element or Document whose bounds are treated as the bounding box of the viewport for the element which is the observer's target. If the root is `null`, then the bounds of the actual document viewport are used. |
140141
| **rootMargin** | `string` | `'0px'` | Margin around the root. Can have values similar to the CSS margin property, e.g. `"10px 20px 30px 40px"` (top, right, bottom, left). Also supports percentages, to check if an element intersects with the center of the viewport for example "-50% 0% -50% 0%". |
141142
| **threshold** | `number` or `number[]` | `0` | Number between `0` and `1` indicating the percentage that should be visible before triggering. Can also be an array of numbers, to create multiple trigger points. |
@@ -152,7 +153,7 @@ Provide these as the options argument in the `useInView` hook or as props on the
152153
The **`<InView />`** component also accepts the following props:
153154

154155
| Name | Type | Default | Description |
155-
|--------------|------------------------------------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
156+
| ------------ | ---------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
156157
| **as** | `IntrinsicElement` | `'div'` | Render the wrapping element as this element. Defaults to `div`. If you want to use a custom component, please use the `useInView` hook or a render prop instead to manage the reference explictly. |
157158
| **children** | `({ref, inView, entry}) => ReactNode` or `ReactNode` | `undefined` | Children expects a function that receives an object containing the `inView` boolean and a `ref` that should be assigned to the element root. Alternatively pass a plain child, to have the `<InView />` deal with the wrapping element. You will also get the `IntersectionObserverEntry` as `entry`, giving you more details. |
158159

@@ -199,8 +200,8 @@ few ideas for how you can use it.
199200
You can wrap multiple `ref` assignments in a single `useCallback`:
200201
201202
```jsx
202-
import React, { useRef, useCallback } from 'react';
203-
import { useInView } from 'react-intersection-observer';
203+
import React, { useRef, useCallback } from "react";
204+
import { useInView } from "react-intersection-observer";
204205

205206
function Component(props) {
206207
const ref = useRef();
@@ -245,7 +246,7 @@ will emulate the real IntersectionObserver, allowing you to validate that your
245246
components are behaving as expected.
246247
247248
| Method | Description |
248-
|-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
249+
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
249250
| `mockAllIsIntersecting(isIntersecting)` | Set `isIntersecting` on all current Intersection Observer instances. The value of `isIntersecting` should be either a `boolean` or a threshold between 0 and 1. |
250251
| `mockIsIntersecting(element, isIntersecting)` | Set `isIntersecting` for the Intersection Observer of a specific `element`. The value of `isIntersecting` should be either a `boolean` or a threshold between 0 and 1. |
251252
| `intersectionMockInstance(element)` | Call the `intersectionMockInstance` method with an element, to get the (mocked) `IntersectionObserver` instance. You can use this to spy on the `observe` and`unobserve` methods. |
@@ -271,11 +272,11 @@ Jest. Otherwise, you'll need to manually setup/reset the mocking in either the
271272
individual tests, or a [setup file](https://vitest.dev/config/#setupfiles).
272273
273274
```js
274-
import { vi, beforeEach, afterEach } from 'vitest';
275+
import { vi, beforeEach, afterEach } from "vitest";
275276
import {
276277
setupIntersectionMocking,
277278
resetIntersectionMocking,
278-
} from 'react-intersection-observer/test-utils';
279+
} from "react-intersection-observer/test-utils";
279280

280281
beforeEach(() => {
281282
setupIntersectionMocking(vi.fn);
@@ -307,7 +308,7 @@ were you actively import `react-intersection-observer/test-utils`.
307308
**test-setup.js**
308309
309310
```js
310-
import { defaultFallbackInView } from 'react-intersection-observer';
311+
import { defaultFallbackInView } from "react-intersection-observer";
311312

312313
defaultFallbackInView(true); // or `false` - whichever consistent behavior makes the most sense for your use case.
313314
```
@@ -320,21 +321,21 @@ Vitest.
320321
321322
```js
322323
module.exports = {
323-
setupFilesAfterEnv: ['react-intersection-observer/test-utils'],
324+
setupFilesAfterEnv: ["react-intersection-observer/test-utils"],
324325
};
325326
```
326327
327328
### Test Example
328329
329330
```js
330-
import React from 'react';
331-
import { screen, render } from '@testing-library/react';
332-
import { useInView } from 'react-intersection-observer';
331+
import React from "react";
332+
import { screen, render } from "@testing-library/react";
333+
import { useInView } from "react-intersection-observer";
333334
import {
334335
mockAllIsIntersecting,
335336
mockIsIntersecting,
336337
intersectionMockInstance,
337-
} from 'react-intersection-observer/test-utils';
338+
} from "react-intersection-observer/test-utils";
338339

339340
const HookComponent = ({ options }) => {
340341
const { ref, inView } = useInView(options);
@@ -345,37 +346,37 @@ const HookComponent = ({ options }) => {
345346
);
346347
};
347348

348-
test('should create a hook inView', () => {
349-
render(<HookComponent/>);
349+
test("should create a hook inView", () => {
350+
render(<HookComponent />);
350351

351352
// This causes all (existing) IntersectionObservers to be set as intersecting
352353
mockAllIsIntersecting(true);
353-
screen.getByText('true');
354+
screen.getByText("true");
354355
});
355356

356-
test('should create a hook inView with threshold', () => {
357-
render(<HookComponent options={{ threshold: 0.3 }}/>);
357+
test("should create a hook inView with threshold", () => {
358+
render(<HookComponent options={{ threshold: 0.3 }} />);
358359

359360
mockAllIsIntersecting(0.1);
360-
screen.getByText('false');
361+
screen.getByText("false");
361362

362363
// Once the threshold has been passed, it will trigger inView.
363364
mockAllIsIntersecting(0.3);
364-
screen.getByText('true');
365+
screen.getByText("true");
365366
});
366367

367-
test('should mock intersecing on specific hook', () => {
368-
render(<HookComponent/>);
369-
const wrapper = screen.getByTestId('wrapper');
368+
test("should mock intersecing on specific hook", () => {
369+
render(<HookComponent />);
370+
const wrapper = screen.getByTestId("wrapper");
370371

371372
// Set the intersection state on the wrapper.
372373
mockIsIntersecting(wrapper, 0.5);
373-
screen.getByText('true');
374+
screen.getByText("true");
374375
});
375376

376-
test('should create a hook and call observe', () => {
377-
const { getByTestId } = render(<HookComponent/>);
378-
const wrapper = getByTestId('wrapper');
377+
test("should create a hook and call observe", () => {
378+
const { getByTestId } = render(<HookComponent />);
379+
const wrapper = getByTestId("wrapper");
379380
// Access the `IntersectionObserver` instance for the wrapper Element.
380381
const instance = intersectionMockInstance(wrapper);
381382

@@ -408,7 +409,7 @@ application can correctly handle all your observers firing either `true` or
408409
You can set the fallback globally:
409410
410411
```js
411-
import { defaultFallbackInView } from 'react-intersection-observer';
412+
import { defaultFallbackInView } from "react-intersection-observer";
412413

413414
defaultFallbackInView(true); // or 'false'
414415
```
@@ -417,8 +418,8 @@ You can also define the fallback locally on `useInView` or `<InView>` as an
417418
option. This will override the global fallback value.
418419
419420
```jsx
420-
import React from 'react';
421-
import { useInView } from 'react-intersection-observer';
421+
import React from "react";
422+
import { useInView } from "react-intersection-observer";
422423

423424
const Component = () => {
424425
const { ref, inView, entry } = useInView({
@@ -447,7 +448,7 @@ yarn add intersection-observer
447448
Then import it in your app:
448449
449450
```js
450-
import 'intersection-observer';
451+
import "intersection-observer";
451452
```
452453
453454
If you are using Webpack (or similar) you could use
@@ -460,8 +461,8 @@ like this:
460461
* Do feature detection, to figure out which polyfills needs to be imported.
461462
**/
462463
async function loadPolyfills() {
463-
if (typeof window.IntersectionObserver === 'undefined') {
464-
await import('intersection-observer');
464+
if (typeof window.IntersectionObserver === "undefined") {
465+
await import("intersection-observer");
465466
}
466467
}
467468
```
@@ -474,13 +475,13 @@ IntersectionObserver instances. This allows you to handle more advanced use
474475
cases, where you need full control over when and how observers are created.
475476
476477
```js
477-
import { observe } from 'react-intersection-observer';
478+
import { observe } from "react-intersection-observer";
478479

479480
const destroy = observe(element, callback, options);
480481
```
481482
482483
| Name | Type | Required | Description |
483-
|--------------|----------------------------|----------|------------------------------------------------------------|
484+
| ------------ | -------------------------- | -------- | ---------------------------------------------------------- |
484485
| **element** | `Element` | true | DOM element to observe |
485486
| **callback** | `ObserverInstanceCallback` | true | The callback function that Intersection Observer will call |
486487
| **options** | `IntersectionObserverInit` | false | The options for the Intersection Observer |
@@ -493,29 +494,13 @@ order to destroy the observer again.
493494
> how instances are created.
494495
495496
[package-url]: https://npmjs.org/package/react-intersection-observer
496-
497497
[npm-version-svg]: https://img.shields.io/npm/v/react-intersection-observer.svg
498-
499-
[npm-minzip-svg]:
500-
https://img.shields.io/bundlephobia/minzip/react-intersection-observer.svg
501-
502-
[bundlephobia-url]:
503-
https://bundlephobia.com/result?p=react-intersection-observer
504-
498+
[npm-minzip-svg]: https://img.shields.io/bundlephobia/minzip/react-intersection-observer.svg
499+
[bundlephobia-url]: https://bundlephobia.com/result?p=react-intersection-observer
505500
[license-image]: http://img.shields.io/npm/l/react-intersection-observer.svg
506-
507501
[license-url]: LICENSE
508-
509502
[downloads-image]: http://img.shields.io/npm/dm/react-intersection-observer.svg
510-
511-
[downloads-url]:
512-
http://npm-stat.com/charts.html?package=react-intersection-observer
513-
514-
[test-image]:
515-
https://github.com/thebuilder/react-intersection-observer/workflows/Test/badge.svg
516-
517-
[test-url]:
518-
https://github.com/thebuilder/react-intersection-observer/actions?query=workflow%3ATest
519-
520-
[test-utils-url]:
521-
https://github.com/thebuilder/react-intersection-observer/blob/master/src/test-utils.ts
503+
[downloads-url]: http://npm-stat.com/charts.html?package=react-intersection-observer
504+
[test-image]: https://github.com/thebuilder/react-intersection-observer/workflows/Test/badge.svg
505+
[test-url]: https://github.com/thebuilder/react-intersection-observer/actions?query=workflow%3ATest
506+
[test-utils-url]: https://github.com/thebuilder/react-intersection-observer/blob/master/src/test-utils.ts

0 commit comments

Comments
 (0)