search

gzimbron / svelte-datagrid

MIT License
11 stars 0 forks source link

readme

npm

Svelte DataGrid

Svelte DataGrid is a high-performance, feature-rich grid component for Svelte. It is designed to handle large datasets and provide a smooth scrolling experience. It is also designed to be accessible and customizable.

It's based on the excellent (but deprecated) svelte-data-grid.

👀 Demo website

Demo website

🚀 Features

📋 TODO

ℹ️ Usage:

Install:

npm install @gzim/svelte-datagrid

Import:

import { Datagrid } from '@gzim/svelte-datagrid';

<Datagrid
    columns={columns}
    rows={myRows}
    rowHeight={24}
    on:valueUpdated={onValueUpdated}
    on:scroll={onGridScroll}
/>;

Datagrid requires 2 properties to be passed in order to display data: rows and columns.

columns is an array of objects containing at least 3 properties: label, dataKey, and width. A svelte component can be specified in headerComponent and cellComponent if any custom cell behavior is required.

[
    {
        label: 'Name', // What will be displayed as the column header
        dataKey: 'firstName', // The key of a row to get the column's data from
        width: 400 // Width, in pixels, of column
    },
    {
        label: 'Age',
        dataName: 'age',
        width: 150
    }
];

rows is an array of objects containing the data for each table row.

[
    {
        firstName: 'Gustavo',
        age: 34
    },
    {
        firstName: 'Paulina',
        age: 31
    },
    {
        firstName: 'Daphne',
        age: 2
    }
];

📝 Editing Data

You can use this 3 componets as cellComponent to edit data:

Import the components:

import { TextboxCell, SelectCell, CheckboxCell } from '@gzim/svelte-datagrid';

Textbox Cell

Textbox cell will debounce the user input.

{
  label: 'Name',
  dataKey: 'name',
  width: 250,
  cellComponent: TextboxCell
}

Select Cell

SelectCell requires that you provide an options array in your cell definition:

{
  label: 'Simpsons Character',
  dataKey: 'simpsonChar',
  width: 200,
  cellComponent: SelectCell,
  options: [
    {
      display: 'Homer',
      value: 'homer'
    },
    {
      display: 'Bart',
      value: 'bart'
    },
    {
      display: 'Lisa',
      value: 'lisa'
    },
    {
      display: 'Marge',
      value: 'marge'
    },
    {
      display: 'Maggie',
      value: 'maggie'
    }
  ]
}

Checkbox Cell

CheckboxCell will set the checked state of the checkbox depending on the boolean value of the row's data.

{
  display: 'Pending',
  dataName: 'pending',
  width: 75,
  cellComponent: CheckboxCell
}

✨ Custom Cell Components

To create a custom cell component, create a new Svelte component following the example below.

Components will be passed the following properties:

MyCustomCell.svelte

<script lang="ts" generics="T">
    import type { GridCellUpdated, GridColumn } from 'datagrid-svelte/types';
    import { createEventDispatcher } from 'svelte';

    type ComponentEventsList = {
        valueUpdated: GridCellUpdated<T>;
    };
    const dispatch = createEventDispatcher<ComponentEventsList>();

    export let row: T;
    export let column: GridColumn<T>;
    export let rowIndex: number;

    const onSomethingHappens = () => {
        dispatch('valueUpdated', {
            row,
            column,
            value: 'newValue',
            rowIndex
        });
    };
</script>

<div class="checkbox-cell" data-row-index="{rowIndex}">ADD HERE YOUR CUSTOM CELL CONTENT</div>

<style lang="postcss">
    .checkbox-cell {
        text-align: center;
    }
</style>

Import the component

import MyCustomCell from './MyCustomCell.svelte';

columns option:

[
  {
    label: 'Icon'
    dataKey: 'icon',
    width: 300,
    cellComponent: MyCustomCell
  }
]

✨ Custom Header Components

Header components can also be specified in columns entries as the headerComponent property. Header components are only passed column, the column object from columns.

<script lang="ts" generics="T">
    import type { GridCellUpdated, GridColumn } from 'datagrid-svelte/types';

    export let column: GridColumn<T>;
</script>

<div class="checkbox-cell"><u>~{ column.label }~</u></div>

<style lang="postcss">
    .checkbox-cell {
        text-align: center;
    }
</style>

🛠️ Options and Functions:

Datagrid provides a few options for controlling the grid and its interactions:

⚙️ Properties

💫 Functions exported

Yoy can bind to the following functions to control the grid:

const getGridState: () => {
    visibleRowsIndexes: {
        start: number;
        end: number;
    };
    scrollTop: number;
    scrollLeft: number;
    yScrollPercent: number;
    xScrollPercent: number;
};
const scrollToRow: (rowIndex: number, behavior: ScrollBehavior = 'smooth') => void;

💄 Styling

Events:

Bugs? Suggestions?

Please file an issue if you find a bug or have a suggestion for a new feature.