svelte-simple-tables

• Features
• Examples
• Installation
• Usage
  • data
  • columnSettings
  • tableSettings
• Themes
  • CSS Custom Properties

Features

• Create sortable, paginated tables that follow WAI-ARIA guidelines.
• Columns dynamically resize to accommodate all visible content.
• Automatically responsive. Tables become horizontally scrollable without breaking page layout.
• Four color themes provided. Users can adjust every detail of existing themes or create new themes with CSS custom properties.

Examples

• svelte-simple-tables docs site
• Coming Soon: CSS Theme Editor

Installation

yarn

yarn add -D @a-luna/svelte-simple-tables

npm

npm install -D @a-luna/svelte-simple-tables

pnpm

pnpm install -D @a-luna/svelte-simple-tables

Usage

<script lang="ts">
    import SimpleTable from '@a-luna/svelte-simple-tables';
    import type { TableSettings } from '@a-luna/svelte-simple-tables/types';
    import { columnSettings } from './columnSettings';
    import type { VaxData } from './data';
    import { data } from './data';

    const tableSettings: TableSettings<VaxData> = {
        tableId: 'vax-status-table',
        themeName: 'darker',
        sortBy: 'age',
        sortDir: 'desc',
        showHeader: true,
        header: 'Vax Status',
        showSortDescription: true,
        tableWrapper: true,
        expandToContainerWidth: true,
        paginated: true,
        pageSize: 10,
        pageSizeOptions: [5, 10, 15, 20, 25],
        pageRangeFormat: 'compact',
        pageNavFormat: 'compact',
        rowType: 'vax records',
    };
</script>

<SimpleTable {data} {columnSettings} {tableSettings} />

SimpleTable expects three props: data, columnSettings, and tableSettings:

data

The data for your table will typically be provided from a response to an API request or database query. In this example, data is imported from a typescript file (data.ts) that exports a list of VaxData objects:

// data.ts
interface VaxData {
    personId: number;
    name: string;
    age: number;
    birthdate: Date;
    vaccinated: boolean;
}

export const data: VaxData[] = [
    {
        personId: 1,
        name: 'Alice',
        age: 11,
        birthdate: new Date(2010, 7, 12),
        vaccinated: true,
    },
    ...// contains 21 items, only showing first and last item for brevity
    {
        personId: 21,
        name: 'Ulysses',
        age: 85,
        birthdate: new Date(1936, 2, 12),
        vaccinated: true,
    },
];

😨 BUT I DON'T WANT TO USE TYPES Why is it necessary to specify the type of the items in the data array? SimpleTable uses an experimental svelte feature that makes it possible to use generic types with component props. This enables advanced error-checking and autocompletion in your IDE.

columnSettings

After you have the data that you wish to display in a table, the next step is to determine which VaxData properties (name, age, etc.) should be displayed in each column. This is accomplished with the columnSettings prop, which is a list of ColumnSettings<VaxData> objects. The API for ColumnSettings<VaxData> is given below:

🚨AS OF VERSION 0.0.26 propType is no longer a property of ColumnSettings<T>. It is no longer necessary to define the type of each value to display as a column, this is automatically inferred for you.

For each column, the only required value is propName (all other properties have sane default values). Determining the value to use for colValue (other than the default) will be necessary quite often, since this controls the value that a column displays for each object.

Let's take a look at an example that renders a column for each VaxData property:

// columnSettings.ts
import type { ColumnSettings } from '@a-luna/svelte-simple-tables/types';
import type { VaxData } from './data';

export const columnSettings: ColumnSettings<VaxData>[] = [
    {
        propName: 'name',
        tooltip: 'First Name',
        colValue: (data: VaxData): string => `<a href="/person/${data.personId}">${data.name}</a>`,
    },
    {
        propName: 'birthdate',
        colValue: (data: VaxData): string => data.birthdate.toDateString(),
    },
    {
        propName: 'age',
    },
    {
        propName: 'vaccinated',
        headerText: 'Vax?',
        tooltip: 'Vaccination Status',
        classList: ['text-center'],
        colValue: (data: VaxData): string => (data.vaccinated ? '✅' : '❌'),
    },
    {
        propName: 'personId',
        headerText: 'ID',
        sortable: false,
    },
];

These five ColumnSettings<VaxData> objects would generate a table similar to the one below:

All of the explanations that follow refer to this table and the ColumnSettings<VaxData> objects defined above.

Example #1: Custom HTML

The first column is configured to display the name property of each object as a link to a hypothetical page. Since colValue is a function which accepts a single VaxData object and returns a string, we can easily construct an anchor element that incorporates properties of the VaxData object:

colValue: (data: VaxData): string => `<a href="/person/${data.personId}">${data.name}</a>`;

This string will be rendered using the special @html tag available in svelte, resulting in a clickable link as shown in the table above.

Example #2: Date value

The birthdate property is a Date value. If the default value for colValue is used, it would be displayed by simply calling the Date.toString() method (e.g., Thu Aug 12 2010 00:00:00 GMT-0700 (Pacific Daylight Time)). By simply configuring colValue to instead call the Date.toDateString() method, the column will omit the time and time-zone information, displaying just the date portion (Thu Aug 12 2010):

colValue: (data: VaxData): string => data.birthdate.toDateString();

Example #3: Number value

The Age column is a good example of when the default behavior produces a result that doesn't require any further changes. The age property is a number, which will be rendered as a string eventually. Therefore, there is no need to customize colValue for this property.

Example #4: Boolean value

The column for vaccinated contains boolean values, which by default will simply display 'true'/'false' strings. The easiest way to display something more interesting is with a ternary operator:

colValue: (data: VaxData): string => (data.vaccinated ? '✅' : '❌');

This column also takes advantage of the classList property. In Tailwind CSS, text-center is a utility class that sets text-align: center on a HTML element. This would add the text-center class to each data cell in this column.

Example #5: Making a Column Unsortable

Finally, the last column displays the personId property. The sortable property is set to false, making this the only column that cannot be sorted by clicking on the column header.

♨️ HOT TIP You can define columnSettings in the <script> tag of your .svelte file, or in a separate .ts file as demonstrated here. If your table has a large number of columns, moving it to its own file will make your .svelte file easier to digest visually and make your component easier to maintain (IMO).

tableSettings

Strictly speaking, the final prop, tableSettings, isn't required. Without it, our table would be rendered like this:

That's a very nice table, I'm sure you will agree. However, by customizing the tableSettings prop, the same data and columnSettings can produce the table below:

Now that's a table that you can be proud of! The tableSettings object specified at the beginning of this README will produce these changes.

🎁Released in 0.0.16
💎Released in 0.0.26

😲 LISTEN UP, CHIEF: As explained above, the tableId prop is used as the id attribute of the table HTML element. Therefore, it is very important that you treat this value as a unique identifier, per HTML requirements. If you choose to provide your own value for tableId , it is extremely important that you do not reuse this value for another SimpleTable component, or any HTML element in your project. Bad things will happen, trust me!

Themes

CSS Custom Properties

The following CSS custom properties can be applied either at the body element (if you want all tables throughout your site to use a single, uniform theme) or can be applied individually to each table. Detailed instructions and an interactive theme editor is a WIP, will be available ASAP:

--sst-font-size
--sst-table-wrapper-border-width
--sst-table-wrapper-border-style
--sst-table-wrapper-padding
--sst-sort-description-font-size
--sst-table-header-font-size
--sst-table-border-radius
--sst-col-header-padding
--sst-col-header-text-weight
--sst-col-header-highlight-text-weight
--sst-body-cell-padding
--sst-button-group-border-radius

--sst-table-wrapper-bg-color
--sst-table-wrapper-border-color

--sst-text-color
--sst-link-text-color
--sst-link-hover-text-color
--sst-table-outer-border-color
--sst-table-header-text-color
--sst-sort-description-text-color
--sst-page-range-description-text-color

--sst-col-header-bg-color
--sst-col-header-text-color
--sst-col-header-vert-border-color
--sst-col-header-horiz-border-color
--sst-col-header-highlight-sort-bg-color
--sst-col-header-highlight-sort-text-color
--sst-col-header-highlight-sort-vert-border-color
--sst-col-header-highlight-sort-horiz-border-color

--sst-body-even-row-bg-color
--sst-body-odd-row-bg-color
--sst-body-inner-vert-border-color
--sst-body-inner-horiz-border-color
--sst-body-highlight-sort-bg-color
--sst-body-highlight-sort-text-color
--sst-body-highlight-sort-border-color

--sst-button-text-color
--sst-button-bg-color
--sst-button-border-color

--sst-button-hover-text-color
--sst-button-hover-bg-color
--sst-button-hover-border-color

--sst-button-active-text-color
--sst-button-active-bg-color
--sst-button-active-border-color

--sst-button-disabled-text-color
--sst-button-disabled-bg-color
--sst-button-disabled-border-color

--sst-button-focus-border-color