React-simple-list2 NPM

react-simple-list2

A collection of list related components I use in my projects

Install

npm i -D react-simple-list2

Usage

This libraries exports five components; ListViewer, ListFilter, ListFilterItem, ListPagination and ObjectViewer

`ListViewer`

Renders a list of items in a tabular form. It also supports templating, where you can use a template function to render each item. To see full usages of this component, view its stories here.

The props for this component are shown below:

Name	Type	Description
`list`	`Array<object>`	The list to render
`emptyListMessage`	`string`	A message to display if the list is empty. Defaults to "No items to display"
`emptyAttrMessage`	`string`	A message to display if a property of an item is empty. Defaults to "-----"
`sortingColumn`	`string`	The column under sort. This allows the sort column to be controlled by the host component
`sortingOrder`	`string`	The sorting order of the list. Values are an empty string, ASC or DESC. This allows the sort order to be controlled by the host component
`attrs`	Array<string, ((item: any, index: number) => any) \| string>	The properties to render for each item
`action`	`(item: any, index: number) => any`	If specified, an additional column is added for each item displaying whatever this function returns
`template`	`(item: any, index: number) => any`	If specified, the `ListViewer` will use it to render a custom JSX for each item. It is passed the item and its index
`onColumnSort`	`(label: string, order: string) => void`	If specified, the column headers will have sorting buttons enabled. If any header is clicked, the `ListViewer` will call this function with the label clicked and the sorting order. The sorting order can be one of ASC, DESC or an empty string for unsorted
`skipIf`	`(item: any, index: number) => boolean`	If specified, this controls whether an item is rendered or not. When this function returns true, the item at that index is skipped.
`keyFn`	`(item: any, index: number) => boolean`	If specified, this assigns unique keys to each rendered item. This function should return a string key which is assigned to the `<tr>` elements.

`ListFilter`

As the name implies, this component provides an easy and consistent way of adding filters to a list. The ListFilterItem actually renders the filter components while the ListFilter manages the state of its ListFilterItems. To see full usages of this component, view its stories here.

The props for the ListFilter are shown below:

Name	Type	Description
`value`	`any`	The state object containing the filter values
`trimNullValues`	`boolean`	If true, keys with null values will be removed from the filter object
`onChange`	`(values: any) => void`	A function that is called when the value of any the filter list item changes. It is passed an object containing the values of each filter item

The props for the ListFilterItem are shown below:

Name	Type	Description
`name`	`string`	The name to use as the key in the object passed to the `ListFilter` `onChange` function
`label`	`string`	The label to show on top of this filter item
`children`	`(config: { value: any; setValue: (val: any) => void }) => any`	The child of the a `ListFilterItem` must be a function which is passed a value and a setValue function. This returns the JSX to be rendered

ListPagination

The pagination allows you to traverse pages of a paginated list quickly. To see full usages of this component, view its stories here.

The props for this component are shown below:

Name	Type	Description
`totalItems`	`number`	The total number of items
`currentPage`	`number`	The current page
`itemsPerPage`	`number`	The number of items rendered in a page (I.e page size)
`displayCount`	`number`	The number of numbered page items to display. Defaults to 2
`onNavigate`	`(page: number) => void`	Called when any of the navigation buttons is clicked. It is passed the page number corresponding to that button

ObjectViewer

This components renders the specified properties of an object in a tabular form. To see full usages of this component, view its stories here.

The props for this component are shown below:

Name	Type	Description
`object`	`any`	The object whose properties are to be rendered
`attrs`	Array<string, ((item: any, index: number) => any) \| string>	A list of properties to render for the object
`emptyAttrMessage`	`string`	A message to display if a property of an item is empty. Defaults to "-----"
`widthRatio`	`number`	The ratio of widths for the label and value column of the table. Defaults to 0.3 (I.e. the label column width is 30% of the width

Storybook

The project uses Storybook to visually test the components

To run these stories:

Clone the repository
Run npm install to install dependencies
Run npm run storybook to start the storybook server.

For more information on Storybook, click here

Maintainers

Kwame Opare Asiedu

Support

If you'd like to support this project, you can do so by becoming a patreon on Patreon

It would be really helpful if you can star the project on Github

Changelog

v1.2.0
- Changed ListFilter to a controlled component.
- Added trimNullValues prop to ListFilter component.
- Removed defaultValue prop from ListFilterItem as parent ListFilter is now a controlled component