ListView control¶
This control renders a list view for the given set of items.
List view control with grouping applied
List view control with drag and drop applied
How to use this control in your solutions¶
- Check that you installed the
@pnp/spfx-controls-react
dependency. Check out the getting started page for more information about installing the dependency. - Import the following modules to your component:
import { ListView, IViewField, SelectionMode, GroupOrder, IGrouping } from "@pnp/spfx-controls-react/lib/ListView";
- Use the
ListView
control in your code as follows:
<ListView
items={items}
viewFields={viewFields}
iconFieldName="FileRef"
compact={true}
selectionMode={SelectionMode.multiple}
selection={this._getSelection}
showFilter={true}
defaultFilter="John"
filterPlaceHolder="Search..."
groupByFields={groupByFields}
dragDropFiles={true}
onDrop={this._getDropFiles}
stickyHeader={true}
className={styles.listWrapper}
listClassName={styles.list} />
-
The control provides full text filtering through all the columns. If you want to execute filtering on the specified columns, you can use syntax :
<ColumnName>
:<FilterValue>
. Use':'
as a separator between column name and value. Control support both'fieldName'
and'name'
properties of IColumn interface. -
With the
selection
property you can define a method that which gets called when the user selects one or more items in the list view:
private _getSelection(items: any[]) {
console.log('Selected items:', items);
}
- With the
groupByFields
property you can define an array of field objects which will be used for grouping.
Important: the same order of the fields defines how grouping will be applied. In the snippet the ListView
control will first group by the Extension
and after that by the Author
field.
const groupByFields: IGrouping[] = [
{
name: "Extension",
order: GroupOrder.ascending
}, {
name: "Author",
order: GroupOrder.descending
}
];
Extend ListView with a ContextualMenu
To extend the ListView
control with a ContextualMenu refer to ListView.ContextualMenu.
- With the
onDrop
handler you can define a method that returns files that where drag and drop by user in the list view:
private _getDropFiles = (files) => {
for (var i = 0; i < files.length; i++) {
console.log(files[i].name);
}
}
Implementation¶
The ListView control can be configured with the following properties:
Property | Type | Required | Description |
---|---|---|---|
iconFieldName | string | no | Specify the items' property name that defines the file URL path which will be used to show the file icon. This automatically creates a column and renders the file icon. |
items | any[] | no | Items to render in the list view. |
viewFields | IViewField[] | no | The fields you want to render in the list view. Check the IViewField implementation to see which properties you can define. |
compact | boolean | no | Boolean value to indicate if the control should render in compact mode. By default this is set to false . |
selectionMode | SelectionMode | no | Specify if the items in the list view can be selected and how. Options are: none, single, multi. |
selection | function | no | Selection event that passes the selected item(s) from the list view. |
groupByFields | IGrouping[] | no | Defines the field on which you want to group the items in the list view. |
defaultSelection | number[] | no | The index of the items to be select by default |
filterPlaceHolder | string | no | Specify the placeholder for the filter text box. Default 'Search' |
showFilter | boolean | no | Specify if the filter text box should be rendered. |
defaultFilter | string | no | Specify the initial filter to be applied to the list. |
dragDropFiles | boolean | no | Specify the drag and drop files area option. Default false. |
onDrop | file | no | Event handler returns files from drag and drop. |
stickyHeader | boolean | no | Specifies if the header of the ListView , including search box, is sticky |
onRenderRow | (props: IDetailsRowProps) => JSX.Element | null | no | Callback to override the default row rendering. |
sortItems | (items: any[], columnName: string, descending: boolean) => any[] | no | Custom sorting function to handle sorting by column |
className | string | no | Class name to apply additional styles on list view wrapper |
listClassName | string | no | Class name to apply additional styles on list view |
The IViewField
has the following implementation:
Property | Type | Required | Description |
---|---|---|---|
name | string | yes | Name of the field. |
displayName | string | no | Name that will be used as the column title. If not defined, the name property will be used. |
linkPropertyName | string | no | Specify the field name that needs to be used to render a link for the current field. |
sorting | boolean | no | Specify if you want to enable sorting for the current field. |
minWidth | number | no | Specify the minimum width of the column. |
maxWidth | number | no | Specify the maximum width of the column. |
isResizable | boolean | no | Determines if the column can be resized. |
render | function | no | Override how the field has to get rendered. |
The IGrouping
has the following implementation:
Property | Type | Required | Description |
---|---|---|---|
name | string | yes | Name of the field |
order | GroupOrder | yes | Specify how the group needs to be ordered. |
enum GroupOrder
Value | Description |
---|---|
ascending | Order the group in ascending order. |
descending | Order the group in descending order. |