https://github.com/toplan/react-hold
:cactus:Automatically show a well-fitting placeholder for dumb component while its content is loading
https://github.com/toplan/react-hold
placeholder react
Last synced: about 2 months ago
JSON representation
:cactus:Automatically show a well-fitting placeholder for dumb component while its content is loading
- Host: GitHub
- URL: https://github.com/toplan/react-hold
- Owner: toplan
- License: mit
- Created: 2017-06-11T14:24:54.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2017-07-04T14:34:25.000Z (almost 8 years ago)
- Last Synced: 2025-03-30T14:11:15.444Z (about 2 months ago)
- Topics: placeholder, react
- Language: JavaScript
- Homepage:
- Size: 145 KB
- Stars: 342
- Watchers: 9
- Forks: 11
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Intro
Automatically show a well-fitting placeholder for dumb component while its content is loading. [[Demo here]](http://toplan.github.io/react-hold/)
[](https://travis-ci.org/toplan/react-hold)
[](https://codecov.io/gh/toplan/react-hold)
[](https://www.npmjs.com/package/react-hold)
[](https://www.npmjs.com/package/react-hold)
- [APIs](#api)
- [Placeholders](#placeholders)
- [Plugins](#plugins)
> What is the meaning of the word **`hold`** in this project? It's means keep(hold) the shape of the dumb component if it without content. You can also see it as an action which make the dumb component has a placeholder.
# Install
```
npm i --save react-hold
```
# Usage
```js
import React from 'react'
import { render } from 'react-dom'
import hold from 'react-hold'
import MyComponent from './path/to/MyCompnent'
// make the bulit-in component has a placeholder
const P = hold('p', (props) => !props.children)
// make the composite component has a placeholder
const MyComponentWithPlaceholder = hold(MyComponent, (props) => !props.data)
class App extends React.Component {
constructor(...args) {
super(...args)
this.state = {
title: '',
data: null,
}
}
render() {
return (
{ this.state.title }
)
}
}
render(, document.body)
```
If you want to make your component has a placeholder by default, try decorator.
```js
import { holdify } from 'react-hold'
@holdify((props) => !props.data)
class MyComponent extends React.Component {
render() {
return
{ this.props.data }
}
}
```
# API
```js
import hold, { holdify } from 'react-hold'
```
### hold(Component, condition, [defaultHolder], [holderDefaultProps])
This is a default API, and it's a higher-order component.
Use it to create a Hold component as a manager to manage the original component and [placeholder](#placeholders) component.
##### Arguments
- `Component` (Component) [Required]: The target(original) component, should be a dumb(presentational) component.
- `condition` (Function) [Required]: The condition function will be called with arguments `props` and `prevProps`.
It needs to returns a boolean value to judge whether to show the placeholder component(`true` means yes).
If returns `false`, the Hold component will remove the placeholder component, and show the original component.
- `defaultHolder` (Component) [Optional]: The default placeholder component. Default [Fill](#fill).
- `holderDefaultProps` (Object) [Optional]: The default props of placeholder component.
##### Returns
(Component): The Hold component which can automatically control the display of original component and placeholder component.
The Hold component supports these props:
- `holder` (Component) [Optional]: The placeholder component, will override the default placeholder.
- `holderProps` (Object) [Optional]: The props of placeholder component, will shallow override the default props.
- `props` (Object) [Optional]: The alias of `holderProps`.
- `innerRef` (Function|String) [Optional]: The ref of original component.
The rest props will be passed to the original component.
### holdify(condition, [defaultHolder], [holderDefaultProps])
The handy decorator made by `hold` API.
# Placeholders
```js
import { Fill, Square, Circle, Text, Table } from 'react-hold/holders'
```
You can import the built-in placeholders from `react-hold/holders`, every different placeholders will display a different content.
##### Common Props
- `color` (String) [Optional]: The color of placeholder. Default `#eee`.
- `cancelHold` (Function): Invoking this function to manually cancel hold the shape of the original component.
This is injected by the Hold component, can't be override.
- `targetProps` (Function): The props of the target(original) component.
This is injected by the Hold component, can't be override.
- `children` [Optional]
### Fill
This placeholder will display a rectangle.
##### Props
- `width` (String|Number) [Optional]: The width of rectangle.
- `height` (String|Number) [Optional]: The height of rectangle.
- `align` (String) [Optional]: If you set a width(such as `300`) lower than the real width of original component,
the rectangle will not fill in the full area, but you can use this prop to set the alignment.
Support `left`, `right` and `center`. Default `center`.
### Square
This placeholder will display a square.
##### Props
- `side` (String|Number) [Optional]: the side length of square.
- `align` (String) [Optional]: Similar to the align prop of `Fill`.
### Circle
This placeholder will display a circle.
##### Props
- `diameter` (String|Number) [Optional]: The diameter of circle.
- `align` (String) [Optional]: Similar to the align prop of `Fill`.
### Text
This placeholder will display a piece of blank text.
##### Props
- `length` (Number) [Optional]: The length of text. Default `100`.
- `lineHeight` (String|Number) [Optional]: the line height of text. Default `2.3`.
- `fontSize` (String|Number) [Optional]: the font size of text. Default `'0.7em'`.
### Table
This placeholder will display a table.
##### Props
- `width` (Number) [Optional]: The width of table.
- `height` (Number) [Optional]: The height of table.
- `cols` (Number) [Optional]: The cols number of table. Default `2`.
- `rows` (Number) [Optional]: The rows number of table. Default `2`.
- `gap` (Number) [Optional]: The gap between cols and rows. Default `2`.
- `align` (String) [Optional]: Similar to the align prop of `Fill`.
# Plugins
- [react-hold-animation](https://github.com/toplan/react-hold-animation):
A higher-order component be use for add animation to the placeholder.
> More cool plugins is in the todo list.
# License
MIT