Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/skovy/react-suspense-img
🖼 A simple React image component that suspends while loading
https://github.com/skovy/react-suspense-img
concurrent image react resource suspense
Last synced: 4 months ago
JSON representation
🖼 A simple React image component that suspends while loading
- Host: GitHub
- URL: https://github.com/skovy/react-suspense-img
- Owner: skovy
- License: mit
- Created: 2019-11-16T21:21:01.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2022-12-04T20:46:01.000Z (about 2 years ago)
- Last Synced: 2024-10-05T14:08:30.990Z (4 months ago)
- Topics: concurrent, image, react, resource, suspense
- Language: TypeScript
- Homepage: https://react-suspense-img.netlify.com
- Size: 592 KB
- Stars: 19
- Watchers: 2
- Forks: 1
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/skovy/react-suspense-img)
**️⚠️ Please note this package relies on experimental React features that are not yet available in a stable release. By definition, this means this package is also experimental. See [the React documentation on current mode for more details](https://reactjs.org/docs/concurrent-mode-intro.html).**
# 🖼 react-suspense-img
A simple React image component that suspends while loading.
## Usage
Install the package.
```bash
yarn add react-suspense-img
```
Import the `Img` component and image `resource` cache.
```tsx
import { Img, resource } from 'react-suspense-img';
```
Use the `Img` component as you would a standard `img` element. However, ensure to wrap it (at the desired place in the tree) with a `ErrorBoundary` and `React.Suspense`. The `Img` component will suspend (while loading) or throw an error (if an error occurred loading the image).
```tsx
// Start fetching early, following the render-as-you-fetch pattern.
resource.preloadImage('https://placekitten.com/12/34');
const Component = () => (
);
```
Want to see examples of what this could look like? See some of
[the examples here](https://react-suspense-img.netlify.com/).
## API
### `![]()
`
A small component that wraps `img` but suspends while the image is loading.
#### Props
- `src`: the only required prop, the image source to display.
- `...`: all of the standard image props, for example `alt`, `className`, etc.
### `resource`
The image resource to cache images and determine if a given image has loaded
or if it needs to suspend.
#### Methods
- `preloadImage(src: string)`: preload the given source image. This is the only
method that is necessary to use. This should be called before using the given
`src` with the `Img` component to follow the
[render-as-you-fetch pattern](https://reactjs.org/docs/concurrent-mode-suspense.html#approach-3-render-as-you-fetch-using-suspense).
- `read(src: string)`: read a given source from the cache. If it has not loaded
it will throw a promise. If it has errored it will throw an error. If it has
loaded it will return the source. This method is used within the `Img`
component and should never need to be called directly.
- `clear()`: clear the entire image resource cache. This may be useful for
running between tests to always start with an empty cache.
## Credit
- Built with [TSDX](https://github.com/jaredpalmer/tsdx).
- Inspired by [`relay-experimental`](https://github.com/facebook/relay/tree/b9d272d58a7101a955e951c735034d39669b40b7/packages/relay-experimental).
- Inspired by [`suspense-experimental-github-demo`](https://github.com/gaearon/suspense-experimental-github-demo).