KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #claude-code #mcp #rust #deepseek-harness #ai-agent #cli

svelte-table

★ 562 Open GitHub ↗

A svelte table implementation that allows sorting and filtering

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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
<script>
  import SvelteTable from "svelte-table";
  const rows = [
    /** data (example below) */
  ];
  const columns = [
    /** columns config (example below) */
  ];
</script>

<SvelteTable columns="{columns}" rows="{rows}"></SvelteTable>
```

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
<script src="iife/SvelteTable.js"></script>
<div id="my-table"></div>
<script>
  var rows = [
    /** data (example below) */
  ];
  var columns = [
    /** columns config (example below) */
  ];
  new SvelteTable({
    target: document.querySelector("#my-table"),
    props: { rows, columns },
  });
</script>
```

## 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
<div class="row">
  <SvelteTable
    columns="{cols}"
    rows="{data}"
    showExpandIcon="{true}"
    expandSingle="{true}"
    rowKey="id"
  >
    <svelte:fragment slot="expanded" let:row>{row.detail}</svelte:fragment>
  </SvelteTable>
</div>
```

### 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
<script>
  const selection = { first_name: "A" };
</script>
<SvelteTable
  columns="{columns}"
  rows="{data}"
  bind:filterSelections="{selection}"
/>
```

## 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";
```

svelte-table

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README