Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aminnairi/react-table

Streamline Your Tables: Effortless Data Control and PresentationReact hook for handling table data
https://github.com/aminnairi/react-table

filter hook react sort table

Last synced: about 5 hours ago
JSON representation

Streamline Your Tables: Effortless Data Control and PresentationReact hook for handling table data

Awesome Lists containing this project

README 

        
# @aminnairi/react-table



Streamline Your Tables: Effortless Data Control and Presentation



## Summary



- [Features](#features)

- [Requirements](#requirements)

- [Installation](#installation)

- [Uninstallation](#uninstallation)

- [API](#api)

   - [useTable](#usetable)

   - [rows](#rows)

   - [sortBy](#sortby)

   - [createSortBy](#createsortby)

   - [filters](#filters)

   - [filterWith](#filterwith)

- [Issue](#issue)

- [License](#license)

- [Contributing](#contributing)

- [Changelog](#changelog)

- [Code of conduct](#code-of-conduct)



[Back to summary](#summary)



## Features



- Simple and Lightweight: Our table handling library is designed to be easy to use and is incredibly lightweight. It won't bloat your project or add unnecessary complexity to your code.

- UI Framework Agnostic: Whether you're using Material UI, TailwindCSS, BootstrapCSS, or any other UI framework, our library can seamlessly integrate into your project. It doesn't impose any specific UI framework requirements.

- Efficient Data Sorting: With the ability to sort your table data by any column, you can easily organize your data in ascending or descending order, providing a better user experience for your application's users.

- Dynamic Filtering: Filter your table data based on multiple criteria, making it straightforward to display only the data that's relevant to your users. Dynamic filtering is made easy, allowing users to search and find what they need quickly.

- TypeScript Support: Our library is written in TypeScript from the ground up. This ensures strong type safety, preventing common mistakes and offering improved code quality and maintainability.

- Customizable and Extensible: The library is designed to be customizable and extensible. You can adapt it to your specific project needs and build on top of it as your application requirements evolve.

- Performance Optimized: We use efficient algorithms and memoization techniques to ensure your table handling remains performant even with large datasets. It's built with performance in mind.

- No Dependencies: Our library doesn't rely on external dependencies, reducing the risk of version conflicts and ensuring a seamless integration into your project.

- Open Source: This library is open source, which means you can contribute to its development, report issues, and benefit from a collaborative community of users.

- Clear and Concise API: The library provides a straightforward API with clear and concise functions, making it easy for developers of all skill levels to use and understand.

- Community Support: Join a community of developers who use this library for their table handling needs. Get help, share your insights, and learn from others in the community.

- Documentation and Examples: We provide extensive documentation and examples to help you get started quickly and make the most of the library's features.

- Continuous Updates: We're committed to maintaining and improving this library. Expect continuous updates and improvements to ensure compatibility with the latest web technologies and best practices.



[Back to summary](#summary)



## Requirements



- Node

- NPM

- React 16.8+



[Back to summary](#summary)



## Installation



```bash

npm install @aminnairi/react-table

```



[Back to summary](#summary)



## Uninstallation



```bash

npm uninstall @aminnairi/react-table

```



[Back to summary](#summary)



## API



### useTable



The `useTable` hook is the core component of our table handling library. It simplifies the process of managing and displaying table data in your application. With this hook, you can efficiently control, sort, and filter your table data with ease. The hook accepts an options object, which includes the `rows` array containing your data and a set of `filters` to specify filtering criteria. You can even customize the filtering algorithm by using the `filterWith` property and provide your own function for filtering rows, or use the default `defaultFilter` function. It returns an object with three key functions: `sortBy`, `createSortBy`, and the `rows` property.



```tsx

import { useTable, filterWith, Filters } from "@aminnairi/react-table";



type Row = {

   id: string,

   email: string

}



const Component = () => {

   const table = useTable>({

      rows: [

         {

            id: "1",

            email: "[email protected]"

         },

         {

            id: "2",

            email: "[email protected]"

         }

      ],

      filters: {

         id: "",

         email: ""

      },

      filterWith: defaultFilter

   });



   return null;

}

```



[Back to summary](#summary)



### rows



The `rows` property is the result of your table handling logic. It provides you with the filtered and sorted data that is ready to be rendered in your UI. This array contains the rows that meet the filter criteria and are sorted according to the chosen column key. The `rows` property simplifies the process of rendering your table, ensuring that you present your data to users in a clear and organized manner. By using this property, you can focus on designing your table's UI without worrying about the underlying data manipulation.



```tsx

import { useTable, defaultFilter, Filters } from "@aminnairi/react-table";



type Row = {

   id: string,

   email: string

}



const Component = () => {

   const { rows } = useTable>({

      rows: [

         {

            id: "1",

            email: "[email protected]"

         },

         {

            id: "2",

            email: "[email protected]"

         }

      ],

      filters: {

         id: "",

         email: ""

      },

      filterWith: defaultFilter

   });



   return (

      

         

            {rows.map(row => (

               

                  

                     {row.id}

                  

                  

                     {row.email}

                  

               

            ))}

         

      

   );

}

```



[Back to summary](#summary)



### sortBy



The `sortBy` function is a fundamental feature of our table handling library. It allows you to sort your table data based on a specified column or key. When called with the desired key, the `sortBy` function reorders the rows in either ascending or descending order, depending on the current sorting order of that column. Sorting can significantly enhance the usability of your table by enabling users to organize data according to their preferences. It's a simple and effective way to make your table more user-friendly.



```tsx

import { useCallback } from "react";

import { useTable, defaultFilter, Filters } from "@aminnairi/react-table";



type Row = {

   id: string,

   email: string

}



const Component = () => {

   const { rows, sortBy } = useTable>({

      rows: [

         {

            id: "1",

            email: "[email protected]"

         },

         {

            id: "2",

            email: "[email protected]"

         }

      ],

      filters: {

         id: "",

         email: ""

      },

      filterWith: defaultFilter

   });



   const sortByIdentifier = useCallback(() => {

      sortBy("identifier");

   }, [sortBy]);



   const sortByEmail = useCallback(() => {

      sortBy("email");

   }, [sortBy]);



   return (

      

         

            

               

                  Identifier

               

               

                  Email

               

            

         

         

            {rows.map(row => (

               

                  

                     {row.id}

                  

                  

                     {row.email}

                  

               

            ))}

         

      

   );

}

```



[Back to summary](#summary)



### createSortBy



The `createSortBy` function is a utility function that works in tandem with `sortBy`. It returns a callback function that is preconfigured to sort the table by a specific column when triggered. This function is particularly useful for scenarios where you want to create sortable column headers in your table. By using `createSortBy`, you can easily assign sorting functionality to specific header cells in a declarative and maintainable manner.



```tsx

import { useTable, defaultFilter, Filters } from "@aminnairi/react-table";



type Row = {

   id: string,

   email: string

}



const Component = () => {

   const { rows, createSortBy } = useTable>({

      rows: [

         {

            id: "1",

            email: "[email protected]"

         },

         {

            id: "2",

            email: "[email protected]"

         }

      ],

      filters: {

         id: "",

         email: ""

      },

      filterWith: defaultFilter

   });



   return (

      

         

            

               

                  Identifier

               

               

                  Email

               

            

         

         

            {rows.map(row => (

               

                  

                     {row.id}

                  

                  

                     {row.email}

                  

               

            ))}

         

      

   );

}

```



[Back to summary](#summary)



### filters



The `filters` option is a key feature for adding dynamic data filtering to your table. It allows you to apply multiple filters to the table data based on column values. By providing a record of filter criteria, you can quickly narrow down the displayed rows to only those that meet the specified conditions. This feature is particularly beneficial when working with large datasets, where users need to find specific information without scrolling through an extensive list of items.



```tsx

import { ChangeEventHandler, useState, useCallback } from "react";

import { useTable, defaultFilter, Filters } from "@aminnairi/react-table";



type Row = {

   id: string,

   email: string

}



const Component = () => {

   const [id, setId] = useState("");

   const [email, setEmail] = useState("");



   const { rows, createSortBy } = useTable>({

      rows: [

         {

            id: "1",

            email: "[email protected]"

         },

         {

            id: "2",

            email: "[email protected]"

         }

      ],

      filters: {

         id,

         email

      },

      filterWith: defaultFilter

   });



   const updateId: ChangeEventHandler = useCallback(event => {

      setId(event.target.value);

   }, [setId]);



   const updateEmail: ChangeEventHandler = useCallback(event => {

      setEmail(event.target.value);

   }, [setEmail]);



   return (

      

         

            

               

                  Identifier

               

               

                  Email

               

            

            

               

                  

               

               

                  

               

            

         

         

            {rows.map(row => (

               

                  

                     {row.id}

                  

                  

                     {row.email}

                  

               

            ))}

         

      

   );

}

```



[Back to summary](#summary)



### filterWith



The `filterWith` property let's you provide a custom function that will go through all rows and filter keys and filter out the rows following your own algorithm. This is useful if you don't like the way it is done by default using the `defaultFilter` function that you can also provide if you don't want to come out with a specially crafted algorithm for filtering rows. This function takes the rows and filters that you already defined and your job is to come out with an algorithm able to filter these rows. The output of this function should be an array of rows.



Below is an example, with the algorithm used in the `defaultFilter` function, simply rewritten for this particular section so you can get inspiration on how it is done under the hood (or read the source-code directly).



```tsx

import { ChangeEventHandler, useState, useCallback } from "react";

import { useTable, Row, Filters } from "@aminnairi/react-table";



export const defaultFilter = >(rows: Array, filters: GenericFilters): Array => {

  return rows.filter(row => {

    return Object.entries(filters).map(([filterKey, filterValue]) => {

      const normalizedRow = String(row[filterKey]);

      const rowParts = normalizedRow.trim().toLowerCase().split(" ")

      const filterParts = filterValue.trim().toLowerCase().split(" ");



      return rowParts.some(rowPart => {

        return filterParts.some(filterPart => {

          return rowPart.includes(filterPart);

        });

      });



    }).every(Boolean);

  });

};



type Row = {

   id: string,

   email: string

}



const Component = () => {

   const [id, setId] = useState("");

   const [email, setEmail] = useState("");



   const { rows, createSortBy } = useTable>({

      rows: [

         {

            id: "1",

            email: "[email protected]"

         },

         {

            id: "2",

            email: "[email protected]"

         }

      ],

      filters: {

         id,

         email

      },

      filterWith: defaultFilter

   });



   const updateId: ChangeEventHandler = useCallback(event => {

      setId(event.target.value);

   }, [setId]);



   const updateEmail: ChangeEventHandler = useCallback(event => {

      setEmail(event.target.value);

   }, [setEmail]);



   return (

      

         

            

               

                  Identifier

               

               

                  Email

               

            

            

               

                  

               

               

                  

               

            

         

         

            {rows.map(row => (

               

                  

                     {row.id}

                  

                  

                     {row.email}

                  

               

            ))}

         

      

   );

}

```



[Back to summary](#summary)



## Issue



The "Issue" section serves as a link or reference to a list of problems, bugs, or tasks that need to be addressed in the project. It typically includes details about what issues exist and what needs to be resolved. This section can help users or contributors quickly navigate to a list of known problems and track progress in addressing them.



See [`issues`](./issues).



[Back to summary](#summary)



## License



The "License" section provides information about the legal terms and conditions under which the project is distributed and used. It specifies how the project's code can be used, modified, and shared. It's crucial to include this section to make it clear to users and contributors what rights and restrictions they have when working with or using the project.



See [`LICENSE`](./LICENSE).



[Back to summary](#summary)



## Contributing



The "Contributing" section outlines guidelines and instructions for individuals who want to contribute to the project. It may include details on how to report issues, how to submit code changes, coding standards, and best practices for contributing effectively. This section helps potential contributors understand the project's workflow and how to get involved.



See [`CONTRIBUTING.md`](./CONTRIBUTING.md).



[Back to summary](#summary)



## Changelog



The "Changelog" section is a historical record of changes made to the project. It typically includes details about each release, such as new features, bug fixes, and other updates. Users and contributors use the changelog to track the project's progress, understand what's new, and assess the impact of changes on their use of the project.



See [`CHANGELOG.md`](./CHANGELOG.md).



[Back to summary](#summary)



## Code of conduct



The "Code of Conduct" section defines the expected behavior and interaction standards for all project participants, including contributors, maintainers, and users. It sets a code of ethics and behavior guidelines to ensure a positive and inclusive environment. This section is essential for fostering a welcoming and respectful community around the project.



See [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).



[Back to summary](#summary)