https://github.com/jamesplease/react-media-ui
https://github.com/jamesplease/react-media-ui
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jamesplease/react-media-ui
- Owner: jamesplease
- License: mit
- Created: 2021-06-30T20:27:40.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-07-16T21:10:24.000Z (almost 4 years ago)
- Last Synced: 2025-02-13T14:44:13.827Z (5 months ago)
- Language: TypeScript
- Size: 712 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# React Media UI
[](https://www.npmjs.com/package/react-media-ui)
Two React components: one for images, one for video.
## Motivation
When images load slowly on the web they will suddenly appear after they have loaded. Or, if
the image is interlaced, it might load in slowly from top to bottom.
Videos behave similarly, and although the built-in video element supports a poster (an
image that appears while the video loads), the poster immediately disappears once the
video has finished loading.
This library provides a different behavior: the image component will fade in if it takes
too long to download, while the video element will cross fade between the poster and the
video.
## Installation
Install using [npm](https://www.npmjs.com):
```
npm install react-media-ui
```
or [yarn](https://yarnpkg.com/):
```
yarn add react-media-ui
```
This library includes a CSS file that must be imported one time. Typically you'll want to bundle
this with the rest of the CSS in your project.
```js
import 'react-media-ui/style.css';
```
## Table of Contents
- [**API Reference**](#api-reference)
- [\](#image-)
- [\](#video-)
- [**Guides**](#guides)
- [Best Practices](#best-practices)
- [Image Placeholder](#image-placeholder)
- [Video Element Performance](#video-element-performance)
- [**Troubleshooting**](#troubleshooting)
## API Reference
### ``
Renders an image. If the image takes a moment to load, then it will fade in once it has loaded.
The `Image` component accepts all of the same props as `![]()
`.
It also accepts a few additional props that most people won't need to use. All of these additional props are optional:
| Prop | Type | Default value | Description |
| ---------------- | ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `threshold` | number | `0.35` | If the image loads faster than this value, then it will not fade in. Specified in units of seconds. |
| `duration` | number | `0.25` | The duration of the fade animation in seconds. |
| `timingFunction` | string | `'ease-out'` | The timing function for the fade animation. [View all valid values here](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function). |
```jsx
// This CSS file must be imported just a single time
import 'react-media-ui/style.css';
import { Image } from 'react-media-ui';
export default function App() {
return ;
}
```
### ``
Renders a video with an optional poster image, which displays until the video has loaded. After the video has ended the
poster image will be fade in again.
The `` component accepts all of the same props as ``. It also accepts a few more, all of which are optional:
| Prop | Type | Default value | Description |
| ------------ | ------------ | ------------- | ------------------------------------------------------------------------------------------------------- |
| `poster` | string | `undefined` | A URL of an image to display while the video loads. |
| `mountVideo` | boolean | `true` | Pass `false` and the video will not be mounted. This can be useful for performance [in certain contexts](#video-element-performance). |
| `imgProps` | `ImageProps` | `undefined` | Props that are passed to the underlying `` element that is used for the poster. |
```jsx
// This CSS file must be imported just a single time
import 'react-media-ui/style.css';
import { Video } from 'react-media-ui';
export default function App() {
return (
);
}
```
## Guides
### Best Practices
Always style your images and videos to have fixed dimensions. That way, they don't
cause the layout of the app to change as assets load in. Also, it allows you to use a
placeholder for your images. (Read the following guide for more!)
In older browsers, you can specify dimensions using `width` and `height`. In newer
browsers, you can specify just one of these along with
[`aspect-ratio`](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio). You may
prefer to use `aspect-ratio` in certain situations, such as 16/9 videos.
```css
.my-video {
width: 100vw;
aspect-ratio: 16/9;
}
```
### Image Placeholder
You may wish to display a placeholder color while the image loads. You can
accomplish this using CSS.
```js
```
```css
.my-image {
/*
Give it explicit dimensions so that it takes up space
even while the image is loading in
*/
width: 120px;
aspect-ratio: 5/8;
/* Specify a background color */
background: #ccc;
/*
You can also round the corners, or do whatever else
you would like!
*/
border-radius: 6px;
overflow: hidden;
}
```
A placeholder background image can be accomplished using this same strategy
(see: [background-image on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/background-image)), although
you will want to be mindful of the image's file size.
### Video Element Performance
Some apps may require swapping out `` elements as a user navigates. If they navigate quickly, then the mounting and unmounting of the underlying video element can
occur rapidly. This can be a problem because mounting and unmounting video elements too rapidly can cause sluggish performance.
To avoid this problem, you can use the `mountVideo` prop.
When the user navigates, set `mountVideo` to `false`. This makes it so that just the poster image mounts. Then, if the user doesn't navigate again after, say, 400ms, set `mountVideo`
back to `true`. This technique ensures that even users who are navigating very quickly will not cause rapid mounting and unmounting of video elements.
## Troubleshooting
### The components aren't displaying as I would expect
Did you remember to import the CSS file?
```js
import 'react-media-ui/style.css';
```
### Animations aren't working
It might be worth doing a quick check that the CSS file was imported.
```js
import 'react-media-ui/style.css';
```
### I'm still having issues
[Open an issue](https://github.com/jamesplease/react-media-ui/issues/new) and I'll try my best to help out!