🌵Automatically show a well-fitting placeholder for dumb component while its content is loading
JavaScript
Switch branches/tags
Nothing to show
Latest commit 71eabd0 Jul 4, 2017 @toplan update
Permalink
Failed to load latest commit information.
examples update Jul 4, 2017
src update words Jul 1, 2017
.babelrc update & tests initial commits Jun 26, 2017
.codecov.yml update ci Jun 28, 2017
.eslintrc.json update & tests initial commits Jun 26, 2017
.gitignore update ci Jun 28, 2017
.npmignore update ci Jun 28, 2017
.travis.yml update ci Jun 28, 2017
LICENSE Initial commit Jun 11, 2017
README.md update Jul 4, 2017
package.json update examples & readme Jul 4, 2017
webpack.config.babel.js update & tests initial commits Jun 26, 2017

README.md

Intro

Automatically show a well-fitting placeholder for dumb component while its content is loading. [Demo here]

build status codecov npm version npm downloads

react-hold-article

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

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 (
      <div className="my-class-name">
        <P>{ this.state.title }</P>
        <MyComponentWithPlaceholder data={this.state.data} />
      </div>
    )
  }
}

render(<App />, document.body)

If you want to make your component has a placeholder by default, try decorator.

import { holdify } from 'react-hold'

@holdify((props) => !props.data)
class MyComponent extends React.Component {
  render() {
    return <div className="add-some-style">{ this.props.data }</div>
  }
}

API

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 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.
  • 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

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

More cool plugins is in the todo list.

License

MIT