@bsara/react-sort

A simple component used for sorting collections and arrays.

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
Minified + gzip package size for @bsara/react-sort in KB

Readme

@bsara/react-sort NPM Package

ISC License

A simple React component used for sorting collections and arrays.

Storybook

Changelog

Install

$ npm i --save @bsara/react-sort

Usage

import React from 'react';
import Sort from '@bsara/react-sort';
import { sort as timsort } from 'timsort';

const comparators = [
  { propPath: 'itemPropName1', type: 'string' },
  { propPath: 'itemPropName2', type: 'number' },
  { propPath: 'itemPropName3', type: 'date' },
  { propPath: 'itemPropName4', type: 'boolean' },

  {
    propPath: 'itemPropName5',
    options:  { myOptionProp: 42 },

    comparator(leftItem, rightItem, options) {
      // Perform comparison...
    }
  },

  function anotherComparator(leftItem, rightItem) {
    // Perform comparison...
  }
];

export default function MyComponent(props) {
  return (
    {/* ... */}

      <Sort
        items={props.items}
        sorter={timsort}
        comparators={comparators}
        render={(sortedItems) => (
          // Render sorted items...
        )} />

      {/* ...or... */}

      <Sort items={props.items}
            sorter={timsort}
            comparators={comparators}>
        {(sortedItems) => (
          // Render sorted items...
        )}
      </Sort>

    {/* ... */}
  );
}

Props

  • items ?Array

    Array of items to be sorted and passed to render/children prop.

  • render(sortedItems) or children(sortedItems) !Function - REQUIRED

    Render function (or function as child) called after items sorting is complete.

  • ascending ?Boolean

    Default option to sort in ascending or descending order.

  • nullsFirst ?Boolean

    Default option to sort with null values first or last.

  • skip ?Boolean

    When true, skips sorting and the value of items prop will be passed to render, unsorted. This is useful in the case where sorting may only be conditionally needed.

  • ignoreCache ?Boolean

    When true, a sort is forced even if none of the cached props have changed. This is useful when a custom comparator has been provided that depends on information outside of the given items prop.

  • sorter(array, comparator) ?Function

    NOTE: If the sorter given does not return an Array, then it is assumed that the array that was given to the sorter was modified.

    Specifying a sorter function allows you to essential control the sorting algorithm used when a sort occurs within the component. By default, Array.prototype.sort is used if no sorter is specified or if sorter is null or undefined.

  • comparator(leftItem, rightItem[, options]) ?Function

    NOTE: This prop takes precedence over the comparators prop and will cause the comparators prop to be ignored if this props is set to a non-null, non-undefined value.

    Comparator function to use when comparing the items found in the given items prop.

  • comparators ?Array<(Function|Object)>

    IMPORTANT: When using this prop, it is assumed that all of the items given are objects and not primitive values like a string, boolean, date, or number.

    NOTE: This prop is ignored if the comparator prop is set to a non-null, non-undefined value.

    A list of comparators and/or comparator configurations to use when comparing the items found in the given items prop. The comparators/configurations are applied in the order that they are found in the comparators array given. If an item in the comparators list is a Function, then that function will just be called with "left" and "right" parameters passed to it (in that order as well). If an item in the comparators list is an Object, then it will be treated as a "configuration". For more information about said "configurations", refer to Comparator Config Properties below.

Comparator Configuration Properties

The comparator configuration objects can take one of two forms: either a comparator is given with some accompanying options, or a propPath and type are given and comparisons are taken care of for you by the Sort component. Below you will find two tables, each describes the properties available for one of the two configuration objects already described.

PropPath/Type Configuration Properties:

* = Required Property

Property Name/Type Type Default Value Description
*propPath String Path to item property to compare.
*type String The type of the value found at propPath.

Allowed Values:
string, number, date, boolean
options Object Comparison options.
options.isAscending Boolean props.ascending When true, items will be sorted in ascending order.
options.nullsFirst Boolean props.nullsFirst When true, null and undefined items will be placed before any defined item.
options.localeIds String Only used when type is "string".
See localeCompare docs for details.
options.usage String Only used when type is "string".
See localeCompare docs for details.
options.localeMatcher String Only used when type is "string".
See localeCompare docs for details.
options.numeric Boolean Only used when type is "string".
See localeCompare docs for details.
options.caseFirst String Only used when type is "string".
See localeCompare docs for details.
options.sensitivity String Only used when type is "string".
See localeCompare docs for details.
options.ignorePunctuation Boolean Only used when type is "string".
See localeCompare docs for details.

Comparator Configuration Properties:

* = Required Property

Property Name/Type Type Default Value Description
*comparator Function Comparator function to use for comparisons.

Function Signature:
comparator(leftParam, rightParam, options)
options Object Comparison options.

(NOTE: options will be passed to comparator as a 3rd function parameter)
options.isAscending Boolean props.ascending When true, items will be sorted in ascending order.


License

ISC License (ISC)

Copyright (c) 2019, Brandon D. Sara (https://bsara.dev/)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.