/react-dynamic-overflow

A React component that lets you know what elements are overflowing.

Primary LanguageJavaScriptMIT LicenseMIT

Travis build status Codecov branch npm downloads MIT License

gzip size size

Maintainability PRs Welcome

react-dynamic-overflow

A React component that lets you know what elements are overflowing.

Getting started

npm install --save react-dynamic-overflow

Why?

react-dynamic-overflow is used for a specific UI pattern.

Imagine you are displaying 1 row of tabs with the same width.

+-------+-------+--------+--------+--------+
| Tab 1 | Tab 2 |  Tab 3 |  Tab 4 |  Tab 5 |
+-------+-------+--------+--------+--------+

When the page gets smaller, the 1 row of tabs may overflow into a second row.

+-------+-------+--------+
| Tab 1 | Tab 2 |  Tab 3 |
+-------+-------+--------+
| Tab 4 | Tab 5 |
+-------+-------+

What if we don't want a second row, and instead display a button that toggles those overflowing elements?

+-------+-------+--------+
| Tab 1 | Tab 2 |  More  |
+-------+-------+--------+

// Clicking on the More button...
+-------+-------+--------+
| Tab 1 | Tab 2 |  More  |
+-------+-------+--------+
                |  Tab 3 |
                +--------+
                |  Tab 4 |
                +--------+
                |  Tab 5 |
                +--------+

react-dynamic-overflow gives you an API that tells you what elements are visible and which have overflowed.

import React from "react";
import DynamicOverflow from "react-dynamic-overflow";

const Example = () => (
  <DynamicOverflow
    list={({ tabRef }) => ([
      <SomeTab ref={tabRef} key={0}>Tab 1</SomeTab>,
      <SomeTab key={1}>Tab 2</SomeTab>,
      <SomeTab key={2}>Tab 3</SomeTab>,
      <SomeTab key={3}>Tab 4</SomeTab>,
      <SomeTab key={4}>Tab 5</SomeTab>,
    ])}
  >
  {
    ({ visibleElements, overflowElements, containerRef }) => {
      return (
        <div ref={containerRef}>
          {visibleElements}

          <div>
            {overflowElements}
          </div>
        </div>
      );
    }
  }
  </DynamicOverflow>
);

API

Props Description Default
children (Function) A render prop function None. This is required
list (Function) A function that returns an array of elements that will be rendered None. This is required
throttle (Number) A number (in milliseconds) in which the resize window event will be throttled 200

children function

The children prop is a function that is called with the following arguments.

Name Description
visibleElements An array of elements from the list props which are visible. The first element will always be visible.
overflowElements An array of elements from the list props which are overflowed.
containerRef A ref function that should be added to the parent element. This element, combined with the tabRef, will be used in determining which elements are overflowed.

list function

The list prop is a function that is called with the following argument.

Name Description
tabRef A ref function that should be added to an element. This element, combined with the containerRef, will be used in determining which elements are overflowed.

Demo

See this CodeSandbox demo.