Wondering what’s next for npm?Check out our public roadmap! »

    @agney/react-loading
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.2 • Public • Published

    React Loading

    Simple and Accessible loading indicators with React.


    code style: prettier

    Comes bundled with React components of Sam Herbert's animated SVG loaders in a tree shakeable package.

    Example of loading indicator SVGs

    Installation

    npm i @agney/react-loading
    # OR 
    yarn add @agney/react-loading

    Demo

    Features

    • Small Size

      The whole library is about 20kB minified. But you would never need the whole bundle.

      The library is build to be treeshakeable that when you use one or two of the bundled loaders, you would have less than 1kB in your bundle.

    • Accessibility

      Provides accessibility attributes on your loading components and containers.

      aria-busy is set to true on container on loading and progress indicators have role=progressbar.

    • Specify a Global loader

      You probably don't want loader components mixed everywhere, so you can specify a LoaderContext that can be overridden later if necessary.

    • Bring your own loader

      If you decide to bring your own loading indicator, library would support that as well, keeping all your logic the same.

    • TypeScript support. Zero extra CSS.

    Usage

    import { useLoading, Audio } from '@agney/react-loading';
     
    function Content() {
      const { containerProps, indicatorEl } = useLoading({
        loading: true,
        indicator: <Audio width="50" />,
      });
     
      return (
        {/* Accessibility props injected to container */}
        <section {...containerProps}>
          {indicatorEl} {/* renders only while loading */}
        </section>
      );
    }

    Loaders

    This library comes bundled with React components of Sam Herbert's animated SVG loaders in a tree shakeable package.

    Each loader is an SVG and all props passed shall be applied to the top SVG element. All SVGs are set to inherit currentColor from it's parents for fill/stroke.

    Available loaders are:

    import {
      Audio,
      BallTriangle,
      Bars,
      Circles,
      Grid,
      Hearts,
      Oval,
      Puff,
      Rings,
      SpinningCircles,
      TailSpin,
      ThreeDots,
    } from '@agney/react-loading';

    Only the ones you use will be included in your bundle when you use a bundler like Webpack/Rollup.

    Context

    You can specify a single loading indicator reused across hooks with the LoaderProvider.

    import { LoaderProvider, useLoading, BallTriangle } from '@agney/react-loading';
     
    function App() {
      const { containerProps, indicatorEl } = useLoading({
        loading: true,
      });
      return <section {...containerProps}>{indicatorEl}</section>;
    }
     
    ReactDOM.render(
      <LoaderProvider indicator={<BallTriangle width="50" />}>
        <App />
      </LoaderProvider>
    );

    You can use as many LoaderProvider provider elements as you like and React will pick the one closest to the hook you are rendering.

    More on React Context

    Extra Props on Loader

    If you want to provide specific props on a loader specifically when you use the hook:

    useLoading({
      loading: true,
      loaderProps: {
        // Any props here would be spread on to the indicator element.
        style: {{ margin: '0 auto' }}
      }
    });

    We also a provide a special key for valueText, that will be used as description for indicator:

    useLoading({
      loading: true,
      loaderProps: {
        valueText: 'Fetching video from the Great Internet',
      },
    });
     
    // now this will generate:
    /* <svg role="progressbar" aria-valuetext="Fetching video from the Great Internet"></svg>*/

    aria-valuetext will be read by screenreaders.

    You could also provide aria-valuenow for indicators that display progress (but the prebundled ones are best for indeterminate progress indicators)

    MDN for Reference on progressbar

    Bring your own loader

    Just switch the import to your own loading indicator (just make sure that it accepts props)

    import { LoaderProvider, useLoading } from '@agney/react-loading';
     
    const Loader = ({ ...rest }) => <{...rest}>Loading...</p>;
     
    function App() {
      const { containerProps, indicatorEl } = useLoading({
        loading: true,
      });
      return <section {...containerProps}>{indicatorEl}</section>;
    }
     
    ReactDOM.render(
      <LoaderProvider indicator={<Loader />}>
        <App />
      </LoaderProvider>
    );

    Contributing

    All PRs welcome.

    Development

    We use tsdx for generating boilerplate.

    Install:

    # Library 
    npm i
     
    # Example 
    cd example && npm i

    Development:

    # Running library dev 
    npm start
     
    # Running example 
    cd example && npm start

    Testing:

    Testing with react-testing-library and jest

    npm test

    Commands are available in detail on tsdx repository.

    Install

    npm i @agney/react-loading

    DownloadsWeekly Downloads

    840

    Version

    0.1.2

    License

    MIT

    Unpacked Size

    130 kB

    Total Files

    32

    Last publish

    Collaborators

    • avatar