elsikora-react-placeholder v3.5.0

Learn about the changes in version 3, or view the v2 documentation.

Basic Usage

Install via one of:

yarn add react-loading-placeholder
npm install react-loading-placeholder

import Placeholder from 'react-loading-placeholder'
import 'react-loading-placeholder/dist/placeholder.css'

<Placeholder /> // Simple, single-line loading placeholder
<Placeholder count={5} /> // Five-line loading placeholder

Principles

Adapts to the styles you have defined

The Placeholder component should be used directly in your components in place of content that is loading. While other libraries require you to meticulously craft a placeholder screen that matches the font size, line height, and margins of your content, the Placeholder component is automatically sized to the correct dimensions.

For example:

function BlogPost(props) {
  return (
    <div>
      <h1>{props.title || <Placeholder />}</h1>
      {props.body || <Placeholder count={10} />}
    </div>
  );
}

...will produce correctly-sized placeholders for the heading and body without any further configuration.

This ensures the loading state remains up-to-date with any changes to your layout or typography.

Don't make dedicated placeholder screens

Instead, make components with built-in placeholder states.

This approach is beneficial because:

1. It keeps styles in sync.
2. Components should represent all possible states — loading included.
3. It allows for more flexible loading patterns. In the blog post example above, it's possible to have the title load before the body, while having both pieces of content show loading placeholders at the right time.

Theming

Customize individual placeholders with props, or render a PlaceholderTheme to style all placeholders below it in the React hierarchy:

import Placeholder, { PlaceholderTheme } from 'react-loading-placeholder';

return (
  <PlaceholderTheme baseColor="#202020" highlightColor="#444">
    <p>
      <Placeholder count={3} />
    </p>
  </PlaceholderTheme>
);

Props Reference

Placeholder only

Placeholder and PlaceholderTheme

Examples

Custom Wrapper

There are two ways to wrap a placeholder in a container:

function Box({ children }: PropsWithChildren<unknown>) {
  return (
    <div
      style={{
        border: '1px solid #ccc',
        display: 'block',
        lineHeight: 2,
        padding: '1rem',
        marginBottom: '0.5rem',
        width: 100,
      }}
    >
      {children}
    </div>
  );
}

// Method 1: Use the wrapper prop
const wrapped1 = <Placeholder wrapper={Box} count={5} />;

// Method 2: Do it "the normal way"
const wrapped2 = (
  <Box>
    <Placeholder />
  </Box>
);

Troubleshooting

The placeholder width is 0 when the parent has display: flex!

In the example below, the width of the placeholder will be 0:

<div style={{ display: 'flex' }}>
  <Placeholder />
</div>

This happens because the placeholder has no intrinsic width. You can fix it by applying flex: 1 to the placeholder container via the containerClassName prop.

For example, if you are using Tailwind, your code would look like this:

<div style={{ display: 'flex' }}>
  <Placeholder containerClassName="flex-1" />
</div>

The height of my container is off by a few pixels!

In the example below, the height of the <div> will be slightly larger than 30 even though the react-loading-placeholder element is exactly 30px.

<div>
  <Placeholder height={30} />
</div>

This is a consequence of how line-height works in CSS. If you need the <div> to be exactly 30px tall, set its line-height to 1. See here for more details.

Contributing

Contributions are welcome! See CONTRIBUTING.md to get started.

Acknowledgements

Our logo is based off an image from Font Awesome. Thanks!