# svelte-table A _relatively_ minimal table component. Allows sorting and filtering based on column values, and row selection/expanding. ## Example [github pages IIFE example](https://dasdaniel.github.io/svelte-table/) ## Install ```sh npm install -save svelte-table ``` ## Usage The package includes exports for raw svelte, ES Module(.mjs) and CJS (.js) exports. Your bundler will likely know which one to pick by using `import SvelteTable from "svelte-table"` ```html ``` An iife version is also available in the `/dist/iife` folder. This allows for easy run-time use, such as a direct uncompiled dependency for a use outside of a svelte project. ```html
``` ## Sample Data and config ```js // define some sample data... const rows = [ { id: 1, first_name: "Marilyn", last_name: "Monroe", pet: "dog" }, { id: 2, first_name: "Abraham", last_name: "Lincoln", pet: "dog" }, { id: 3, first_name: "Mother", last_name: "Teresa", pet: "" }, { id: 4, first_name: "John F.", last_name: "Kennedy", pet: "dog" }, { id: 5, first_name: "Martin Luther", last_name: "King", pet: "dog" }, { id: 6, first_name: "Nelson", last_name: "Mandela", pet: "cat" }, { id: 7, first_name: "Winston", last_name: "Churchill", pet: "cat" }, { id: 8, first_name: "George", last_name: "Soros", pet: "bird" }, { id: 9, first_name: "Bill", last_name: "Gates", pet: "cat" }, { id: 10, first_name: "Muhammad", last_name: "Ali", pet: "dog" }, { id: 11, first_name: "Mahatma", last_name: "Gandhi", pet: "bird" }, { id: 12, first_name: "Margaret", last_name: "Thatcher", pet: "cat" }, { id: 13, first_name: "Christopher", last_name: "Columbus", pet: "dog" }, { id: 14, first_name: "Charles", last_name: "Darwin", pet: "dog" }, { id: 15, first_name: "Elvis", last_name: "Presley", pet: "dog" }, { id: 16, first_name: "Albert", last_name: "Einstein", pet: "dog" }, { id: 17, first_name: "Paul", last_name: "McCartney", pet: "cat" }, { id: 18, first_name: "Queen", last_name: "Victoria", pet: "dog" }, { id: 19, first_name: "Pope", last_name: "Francis", pet: "cat" }, // etc... ]; // define column configs const columns = [ { key: "id", title: "ID", value: v => v.id, sortable: true, filterOptions: rows => { // generate groupings of 0-10, 10-20 etc... let nums = {}; rows.forEach(row => { let num = Math.floor(row.id / 10); if (nums[num] === undefined) nums[num] = { name: `${num * 10} to ${(num + 1) * 10}`, value: num }; }); // fix order nums = Object.entries(nums) .sort() .reduce((o, [k, v]) => ((o[k] = v), o), {}); return Object.values(nums); }, filterValue: (r, f) => f === Math.floor(r.id / 10), headerClass: "text-left", }, { key: "first_name", title: "FIRST_NAME", value: v => v.first_name, sortable: true, filterOptions: rows => { // use first letter of first_name to generate filter let letrs = {}; rows.forEach(row => { let letr = row.first_name.charAt(0); if (letrs[letr] === undefined) letrs[letr] = { name: `${letr.toUpperCase()}`, value: letr.toLowerCase(), }; }); // fix order letrs = Object.entries(letrs) .sort() .reduce((o, [k, v]) => ((o[k] = v), o), {}); return Object.values(letrs); }, filterValue: (r, f) => f === r.first_name.charAt(0).toLowerCase(), }, { key: "last_name", title: "LAST_NAME", value: v => v.last_name, sortable: true, filterOptions: rows => { // use first letter of last_name to generate filter let letrs = {}; rows.forEach(row => { let letr = row.last_name.charAt(0); if (letrs[letr] === undefined) letrs[letr] = { name: `${letr.toUpperCase()}`, value: letr.toLowerCase(), }; }); // fix order letrs = Object.entries(letrs) .sort() .reduce((o, [k, v]) => ((o[k] = v), o), {}); return Object.values(letrs); }, filterValue: (r, f) => f === r.last_name.charAt(0).toLowerCase(), }, { key: "pet", title: "Pet", value: v => v.pet, renderValue: v => v.pet.charAt(0).toUpperCase() + v.pet.substring(1), // capitalize sortable: true, filterOptions: ["bird", "cat", "dog"], // provide array }, ]; ``` ## Props | Option | Type | Description | | -------------------------- | --------------- | ----------------------------------------------------------------------- | | `columns` | Object[] | column config (details below) | | `rows` | Object[] | row (data) array | | `sortBy` | String | ‡ Sorting key | | `sortOrder` | Number | ‡ `1` = Ascending, `-1` Descending, `0` no filtering | | `sortOrders` | Number[] | availability of order options | | `iconAsc` | String | (_html_) override ascending order indication | | `iconDesc` | String | (_html_) override descending order indication | | `iconFilterable` | String | (_html_) override filterable column indication | | `iconExpand` | String | row collapsed indicator/button | | `iconExpanded` | String | row expanded indicator/button | | `iconSortable` | String | indicate column is sortable | | `classNameTable` | String/Array | _optional_ class name(s) for table element | | `classNameThead` | String/Array | _optional_ class name(s) for thead element | | `classNameTbody` | String/Array | _optional_ class name(s) for tbody element | | `classNameSelect` | String/Array | _optional_ class name(s) for filter select elements | | `classNameInput` | String/Array | _optional_ class name(s) for search input elements | | `classNameRow` | String/function | _optional_ class name(s) for row elements. Supports passing function | | `classNameRowExpanded` | String/Array | _optional_ class name(s) for expanded row | | `classNameExpandedContent` | String/Array | _optional_ class name(s) for expanded row content | | `classNameRowSelected` | String/Array | _optional_ class name(s) for selected row | | `classNameCell` | String/Array | _optional_ class name(s) for cell elements | | `classNameCellExpand` | String/Array | _optional_ class name(s) for cell with expand icon | | `expanded` | String[] | ‡ _optional_ array of key values of expanded rows | | `expandRowKey` | String | _optional_ **deprecated** use `rowKey` | | `rowKey` | String | _optional_ key for expanded or selected row (use unique values like id) | | `expandSingle` | Boolean | _optional_ default: `false` allow only one row to be selected | | `selected` | String[] | ‡ _optional_ array of key values of selected rows | | `selectSingle` | Boolean | _optional_ default: `false` allow only one row to be selected | | `selectOnClick` | Boolean | _optional_ default: `false` will clicking on row will update selection | | `filterSelections` | Object[] | ‡ _optional_ search or filter selection | | `filteredRows` | Object[] | ‡ _optional_ returns the filtered rows | | `showExpandIcon` | Boolean | should a expand column be visible | _‡_ field allows 2-way binding ### Events Events pass a CustomEvent object with the following params in the `detail` object | event | detail parameters | Description | | ------------- | --------------------- | --------------- | | `clickCol` | `event`, `col`, `key` | click on column | | `clickRow` | `event`, `row` | click on a row | | `clickCell` | `event`, `row`, `key` | click on a cell | | `clickExpand` | `event`, `row` | click expand | ### Expanding Rows - Row expanding is tracked using the `expanded` property. (supports 2-way binding) - The keys are defined using the `rowKey` property (previously `expandRowKey` which is getting deprecated). It is recommended to use a key that is unique to each row like a dedicated id or key field, to prevent conflict. - The content for the field is passed through the `expanded` slot. - The expanding can be managed manually or by using the built-in column using `showExpandIcon` property - Expand events can be listened to using `on:clickExpand` which will include the `row` object in the `event.detail` object. - `expandSingle` can be set to true to only allow a single column open at a time - `expandSingle` does not inforce single row expansion when multiple keys are is passed to `expanded` - Row expanded status is available through the `$expanded` property of the row, but is consdered an internal and may be removed Example: ```html
{row.detail}
``` ### Selecting Rows - By default, selection functionality is disabled, enable through `selectOnClick` - Row selection is tracked by `selection` property and supports 2-way binding - Selection happens when user clicks on row - Use `classNameRowSelected` to assign class to a selected row - Selection is tracked using the key defined by the `rowKey` property - The selection prop is an array because it supports both single and multiple selections - Multiple vs. single selection is handled through `selectSingle` - `selectSingle` does not enforce single row selection when multiple keys are is passed to `selection` - Row selection status is available through the `$selected` property of the row, but is considered an internal and may be removed ### Filtering order Providing `sortOrders` specifies the column filtering orders. `sortOrders = [1, -1, 0]` indicates that the row will be sorted ascending (`1`), then descending (`-1`), then going back without any filter (`0`), ### `filterSelections` Allows getting and setting the search or filter value. The `filterSelections` will update as the filter and search selection changes. Inside the object keys (matching row keys) will be used to get/set the filter and search values. Setting key to `undefined` or deleting it will remove filter or search setting. example: (will preset column with key `first_name` to `a`) ```html ``` ## Column array object values | Option | Type | Description | | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------ | | `key` | String | Unique key identifying the column | | `title` | String | Title for header | | `value` | Function | table cell value. The function is passed row data | | `[class]` | String | _optional_ table cell class name | | `[sortable]` | Boolean | _optional_ Whether the table can be sorted on column | | `[searchValue]` | Function | _optional_ search value function. function is passed row data and serach term | | `[filterOptions]` | Array/Function | _optional_ array of objects with `name` and `value`. Function is passed an array of rows | | `[filterValue]` | Function | _optional_ filter value function, 1 or 2 parameter function | | `[filterPlaceholder]` | String | _optional_ placeholder attribute for the filter input or select dropdown | | `[hideFilterHeader]` | Boolean | _optional_ will hide search or filter input in header | | `[headerClass]` | String | _optional_ class to assign to header element | | `[headerFilterClass]` | String | _optional_ class to assign to search/filter header element | | `[renderValue]` | Function | _optional_ render function for rendering html content | | `[renderComponent]` | Component | _optional_ pass a Svelte component, it will receive `row` and `col` variables (replaces `renderValue`) | | `[parseHTML]` | Boolean | _optional_ if true, it will render the cell value with `@html` | ### `searchValue` #### Option 1: `searchValue(row, searchTerm):boolean` Define a function that accepts a row and the searchTerm, the comparison is defined within the function and the match is returned in the form of a boolean. This is the recommended way of using the search (added in v0.5.3) #### Option 2: `searchValue(row):string` Define a function that accepts a row and returns a string. SveltTable does the comparison internally, but only supports case-insensitive compare using `includes` This behaviour is set for deprecation and should not be used. If you want to migrate the existing behaviour you can use this example: ```js searchValue: (v, s) => v["some_key"].toString().toLowerCase().includes(s.toLowerCase()), ``` ### `filterValue` #### Option 1: `(row, filterSelection)=>boolean` By passing a 2 parameter function, the function can be used to define filter functionality. This allows filtering using things like `includes` on an array. Instead of defining a set of preset filter functionalities, this allows more control #### Option 2: `(row)=>string` This feature is set for deprication in favor of Option #1. By passing a 1 parameter function, the table will filter based on the returned string matching the filter selection. Also note that the functionality matches the passed `value` function, which it defaults to when not defined. There is an option to define both in case the value and filter value needs to be different. ### `renderComponent` Defining a component can be done directly by passing the component as a value ```js [ { key: "myColumn", //... renderComponent: myComponent, }, ]; ``` Or, if props need to be passed, an object with `component` and `props` can be passed. ```js [ { key: "myColumn", //... renderComponent: { component: myComponent, props: { myProp: "someValue", }, }, }, ]; ``` ## Slots | Option | Description | | ---------- | ---------------------------------------------------------------------------------------------- | | `header` | slot for rendering the `tr` and `th` content. This will replace `title` in the header | | `row` | slot for rendering the `tr` and `td` content. This will replace the rendering of `renderValue` | | `expanded` | slot for rendering the content of the expanded row | --- ### Conditional row and cell class names By passing a function to `classNameRow` the rows can have class assigned for the tr element based on the row value. The function is provided two arguments, the row value, and the row index. ```js // classNameRow function type definition (row: Row, rowIndex?: number) => string | null; ``` This is an example of using the row index make a striped table, which may be needed when rows are expandable. ```js (row, rowIndex) => (rowIndex % 2 == 0 ? null : "row-odd"); ``` Individual cells can also be formatted by passing a function to the `class` prop in the column object. The class function is provided three parameters. In addition to the row and rowIndex, it also provides the column index ```js // classs function type definition (row: Row, rowIndex?: number, colIndex?: number) => string | null; ``` example for a checker-board pattern: ```js (row, rowIndex, colIndex) => (rowIndex + colIndex) % 2 == 0 ? null : "cell-odd"; ``` example using a value from the row object: ```js row => row.count > 10 && "cell-valid"; ```