@aminnairi/react-table
v1.0.2
Published
Streamline Your Tables: Effortless Data Control and Presentation
Downloads
73
Readme
@aminnairi/react-table
Streamline Your Tables: Effortless Data Control and Presentation
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.
Requirements
- Node
- NPM
- React 16.8+
Installation
npm install @aminnairi/react-tableUninstallation
npm uninstall @aminnairi/react-tableAPI
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.
import { useTable, filterWith, Filters } from "@aminnairi/react-table";
type Row = {
id: string,
email: string
}
const Component = () => {
const table = useTable<Row, Filters<Row>>({
rows: [
{
id: "1",
email: "[email protected]"
},
{
id: "2",
email: "[email protected]"
}
],
filters: {
id: "",
email: ""
},
filterWith: defaultFilter
});
return null;
}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.
import { useTable, defaultFilter, Filters } from "@aminnairi/react-table";
type Row = {
id: string,
email: string
}
const Component = () => {
const { rows } = useTable<Row, Filters<Row>>({
rows: [
{
id: "1",
email: "[email protected]"
},
{
id: "2",
email: "[email protected]"
}
],
filters: {
id: "",
email: ""
},
filterWith: defaultFilter
});
return (
<table>
<tbody>
{rows.map(row => (
<tr key={row.id}>
<td>
{row.id}
</td>
<td>
{row.email}
</td>
</tr>
))}
</tbody>
</table>
);
}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.
import { useCallback } from "react";
import { useTable, defaultFilter, Filters } from "@aminnairi/react-table";
type Row = {
id: string,
email: string
}
const Component = () => {
const { rows, sortBy } = useTable<Row, Filters<Row>>({
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 (
<table>
<thead>
<tr>
<th onClick={sortByIdentifier}>
Identifier
</th>
<th onClick={sortByEmail}>
Email
</th>
</tr>
</thead>
<tbody>
{rows.map(row => (
<tr key={row.id}>
<td>
{row.id}
</td>
<td>
{row.email}
</td>
</tr>
))}
</tbody>
</table>
);
}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.
import { useTable, defaultFilter, Filters } from "@aminnairi/react-table";
type Row = {
id: string,
email: string
}
const Component = () => {
const { rows, createSortBy } = useTable<Row, Filters<Row>>({
rows: [
{
id: "1",
email: "[email protected]"
},
{
id: "2",
email: "[email protected]"
}
],
filters: {
id: "",
email: ""
},
filterWith: defaultFilter
});
return (
<table>
<thead>
<tr>
<th onClick={createSortBy("identifier")}>
Identifier
</th>
<th onClick={createSortBy("email")}>
Email
</th>
</tr>
</thead>
<tbody>
{rows.map(row => (
<tr key={row.id}>
<td>
{row.id}
</td>
<td>
{row.email}
</td>
</tr>
))}
</tbody>
</table>
);
}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.
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<Row, Filters<Row>>({
rows: [
{
id: "1",
email: "[email protected]"
},
{
id: "2",
email: "[email protected]"
}
],
filters: {
id,
email
},
filterWith: defaultFilter
});
const updateId: ChangeEventHandler<HTMLInputElement> = useCallback(event => {
setId(event.target.value);
}, [setId]);
const updateEmail: ChangeEventHandler<HTMLInputElement> = useCallback(event => {
setEmail(event.target.value);
}, [setEmail]);
return (
<table>
<thead>
<tr>
<th onClick={createSortBy("identifier")}>
Identifier
</th>
<th onClick={createSortBy("email")}>
Email
</th>
</tr>
<tr>
<th>
<input value={id} onChange={updateId} />
</th>
<th>
<input value={email} onChange={updateEmail} />
</th>
</tr>
</thead>
<tbody>
{rows.map(row => (
<tr key={row.id}>
<td>
{row.id}
</td>
<td>
{row.email}
</td>
</tr>
))}
</tbody>
</table>
);
}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).
import { ChangeEventHandler, useState, useCallback } from "react";
import { useTable, Row, Filters } from "@aminnairi/react-table";
export const defaultFilter = <GenericRow extends Row, GenericFilters extends Filters<Row>>(rows: Array<GenericRow>, filters: GenericFilters): Array<GenericRow> => {
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<Row, Filters<Row>>({
rows: [
{
id: "1",
email: "[email protected]"
},
{
id: "2",
email: "[email protected]"
}
],
filters: {
id,
email
},
filterWith: defaultFilter
});
const updateId: ChangeEventHandler<HTMLInputElement> = useCallback(event => {
setId(event.target.value);
}, [setId]);
const updateEmail: ChangeEventHandler<HTMLInputElement> = useCallback(event => {
setEmail(event.target.value);
}, [setEmail]);
return (
<table>
<thead>
<tr>
<th onClick={createSortBy("identifier")}>
Identifier
</th>
<th onClick={createSortBy("email")}>
Email
</th>
</tr>
<tr>
<th>
<input value={id} onChange={updateId} />
</th>
<th>
<input value={email} onChange={updateEmail} />
</th>
</tr>
</thead>
<tbody>
{rows.map(row => (
<tr key={row.id}>
<td>
{row.id}
</td>
<td>
{row.email}
</td>
</tr>
))}
</tbody>
</table>
);
}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.
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.
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.
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.
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.