Grid builder plugin for Vue 3

The grid builder component dynamically generates tables based on the provided rows data and a JSON columns configuration.

Key Features

1. Column Types

• Predefined Types:
• text: Displays plain text and if sortabel sorted alphabetically.
• number: Displays number that can be formtated with NumberFormatOptions and sorted numerically .
• image: Renders an image.
• link: Displays hyperlinks (with customizable text and URL behavior).
• badge: Displays styled labels or badges.
• date: Formats and displays dates.
• actions: Includes buttons or action elements.
• Custom Types:
• Register custom field types for unique cell content rendering.

2. Data Handling

• Accepts data in the rows prop to populate the table.
• Supports cell-level customization for data formatting.

3. Pagination

• Built-in pagination for handling large datasets.
• Configurable to match specific requirements (e.g., rows per page).

4. Customizable Styles

• Provides options to style the table (e.g., striped rows, borders).
• Supports global configs and per-instance overrides.

Installation

npm install vi-grid-builder

Integrate plugin in Vue app

import ViGridBuilder from "vi-grid-builder";
import {createApp} from 'vue'
import App from './App.vue'

const app = createApp(App).use(ViGridBuilder)

Import the style

@import "vi-grid-builder/style.css";

Examples

If you want to see usage examples download the project and run

cd playgorund

npm run dev

Table options

| option | type | description | default value | |--------------------|----------|-------------------------------------------------------------------------------|-------------------------------------| | rows | Array | Data that needs to be displayed in the table | /
| row-key | String | Name of the field that is unique identifier for a single row | /
| columns | Array | Config for the column (in details below) | /
| title | String | Title for the table | /
| pagination | Object | Pagination config for the rows | in detilas under pagination section | rowsNumber | Number | Total number of rows | /
| disable-pagination | Boolean | Option to hide pagination | false
| server-mode | Boolean | Is data fetched from server | true
| fetch-server-data | Function | Function that will fetch data from server | /
| fetch-on-init | Boolean | On initialisation make request to fetch data | true
| filter | fdf | fdf | fr
| loading | Boolean | For server side loading is handled, for client side you can you this prop | false
| no-data-label | String | Text to display when there is no data in the table | No data found
| no-cell-data-label | String | Text to display if there is no value for the cell | "/" is displayed by default
| clcikable-row | Boolean | emits rowClicked event with row as argumnet | false

Header options

| option | type | decsription | default value |--------|--------|---------------------|--------------- | title | String | title for the table | /

Header slots

| name | description | props
|------------------------------|--------------------------------------------------------|--------| | title | slot for displaying title on top of the table | title
| vi-header-cell-[column_name] | slot for override default header cell for each column | column

Columns options

| option | type | description | default value | |-----------|------------------------------------------|-------------------------------------------------------|--------------------------------| | label | String | Title for the column | / | | type | text, link, image, date, badge, actions | Type of the field | text
| name | String | Name of the field for which data will be presented | / | | sortable | Boolean | Is the column sortable? | false | | isVisible | Boolean | Is the column visible? | true | | transform | Function | Function to cange | format the data before display | / | | align | centre, left, right | How to align the content in the cells for this column | / | | sort | Function | Compare function for sorting data in this column | / |

Aditional columsn options for sepcific fields

field type | option | type | description | default value | |------------|----------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| | date | mode | date,time, dateTime | what part of the date shoudl be displayed | dateTime
| date | format | object | format of date field | {date:"yyyy-MM-dd",dateTime:"yyyy-MM-dd HH:mm:ss",time:"HH:mm:ss",} date-fns is used for formtatiin | | actions | actions | Array of object | Option for field of type action | every object should have unique action field and name for the text displayed for the action | | actions | kebab | boolean | should action menu be 'kebab type' | false | | link | String | link field | If the link field is provided, it is used as the URL, and name is used as the link text. If the link field is not provided, both the URL and link text default to the name field value. | /
| number | format | object - NumberFormatOptions | format of number field | ex: {style: 'currency',currency: 'USD'} | | text | editable | boolean | if true it will show input to edit the field value, adn willl emit event rowValueUpdated | ex: {style: 'currency',currency: 'USD'} |

Example config for columns

columns: [{
    label: 'ID',
    name: 'id',
    type: 'number',
    sortable: true,
},
    {
        label: 'Title',
        name: 'title',
    },
    {
        label: 'Link',
        name: 'link',
        type: 'link',
        // link:'link'
    },
    {
        label: 'Link with title',
        name: 'title',
        type: 'link',
        link: 'link'
    },
    {
        label: 'Price',
        name: 'price',
        type: 'number',
        sortable: true,
        format: {
            style: 'currency',
            currency: 'USD',
        }
    },
    {
        label: 'Image',
        name: 'image',
        type: 'image'
    },
    {
        label: 'Status',
        name: 'status',
        type: 'badge'
    },
    {
        label: 'Date',
        name: 'date',
        type: 'date',
        mode: 'date'
    },
    {
        label: 'Time',
        name: 'date',
        type: 'date',
    },
    {
        label: 'Simple actions',
        name: 'actions',
        type: 'actions',
        actions: [
            {
                action: 'edit',
                name: 'Edit post'
            },
            {
                action: 'remove',
                name: 'Remove post'
            }
        ]
    },
    {
        label: 'Kebab type actions',
        name: 'actions',
        type: 'actions',
        kebab: true,
        actions: [
            {
                action: 'edit',
                name: 'Edit post'
            },
            {
                action: 'remove',
                name: 'Remove post'
            }
        ]
    },
]

Table body slots

| name | description | props
|------------|---------------------------------------------------------------|------------| | empty-data | slot for when no data in table | /
| loading | slot for displaying loading when data is fetching from server | /
| footer | slot for overriding footer of table | pagination

Registering custom field type

By default the gird builder for displaying data in the cells supports the following types of fields : text, **link **, image, date , badge, actions and checkbox?. If this fields does not full-fill the needs for you application you can register your own type of fields. For example if we need an "avatar" field that will display the user's picture and if there is no picture for the user it will display the user's initials. First we need to create the component for the new field, and then we need to define it in the options for the plugin. Props that you will receive for the custom field are:

• field - all options for the column
• value - value for the field or '/' if no value
• original-value - original value for the field
• row - value for the whole row (ex if the table display name and id of a user, that row would be one user)

The component can look like this

<template>
  <div class="avatar">
    <img v-if="row.picture"
         :src="row.picture" alt="User Avatar" class="avatar-img"/>
    <div v-else class="avatar-initials">{{initials}}</div>
  </div>
</template>

<script>
  export default {
    name: 'UserAvatar',
    props: {
      
      value: {},
      originalValue: {},
      row: {
        type: Object,
      }
    },
    computed: {
      initials() {
        if (this.row.name) {
          const nameParts = this.row.name.split(' ');
          return nameParts.map(part => part[0].toUpperCase()).join('');
        }
        return '';
      }
    }
  };
</script>

Then we need to add this component as part of the settings for the plugin. See example:

import UserAvatar from "./components/user/UserAvatar.vue";
import ViGridBuilder from "vi-grid-builder";

const app = createApp(App)
    .use(ViGridBuilder, {
        fieldComponents: {
            UserAvatar
        }
    })

After adding the component in the fieldComponents we can use the new field type in the definition for the columns, like this

columns: [
    {
        label: 'User',
        type: 'user-avatar',
        name: 'picture',
    }]

Pagination

Pagination is passed as object in table prop, the obejct should have this fields:

| name | type | description | default value |-------------|------------------|--------------------------------------------------------|---------------| | page | Number | number for the current page | /
| rowsPerPage | Number | number of rows displayed per page | 10
| rowsNumber | Number | number of total avaliable rows - only for server side | /
| sortBy | array of objects | sort by field and direction | null

Pagination otpions

| name | type | description | default value |--------------------|------------------|--------------------------------------------------------|---------------| | disablePagination | Boolean | hide pagination | false
| compactPagination | Boolean | should the pagination be compact (no pages displayed) | false
| rowsPerPageOptions | Array of obecjts | Droprdown options for displayin how many rows per page | /

CSS CLASSES

| class name | description
|-----------------------------|------------------------------------------------------------------------| | .vi-table-container | wrapper around table | | .vi-table-container.loading | classes for loading state of table | | .vi-table | class for the table tag | | .vi-table.stripped | class used to apply alternating background colors to table rows | | .vi-table.bordered | class used to apply borders on table cells | | .vi-table-head | class for the head tag | | .vi-table-body | class for the tbody tag | | .vi-table-row | class for all rows in table | | .vi-header-row | class for rows only in table header | | .vi-body-row | class for rows only in table body | | .vi-body-row.selected | class for selected row | | .vi-body-row.clickable | class for clickable row | | .vi-title-row | class for row that displays the table tite | | .vi-loading-row | class for row that holds the loading bar | | .vi-no-data-row | class for row that appears when no data is avaliable in table | | .vi-cell | class for all cells in table | | .vi-header-cell | class for header cells in table | | .vi-body-cell | class for body cells in table | | .vi-header-cell-content | class that wrapes content in header cells | | .vi-select-cell | class for cells that holds checkbox for selecting row or master select | | .vi-grid-field | wraaper clas for content in body cells | | .vi-footer-row | class for last row in table that holds usually pagination | | .vi-footer-cell | class for cell in last row |

GLOBAL SETTINGS

Grid props that can be set globally

• align: center, left,right
• bordered: boolean
• stripped: boolean
• disablePagination: boolean
• noDataLabel: String
• noCellDataLabel: String
• compactPagination: boolean
• rowsPerPageOptions: Array

Example:

import {createApp} from 'vue'
import App from './App.vue'

const app = createApp(App);
app.use(ViGridBuilderPlugin, {
    align: 'right',
    compactPagination: true,
    noDataLabel: 'emtpy table data',
    noCellDataLabel: 'NA',
    stripped: true,
    bordered: true,
    rowsPerPage: 30,
    rowsPerPageOptions: [{
        label: 15,
        value: 15
    }, {
        label: 20,
        value: 20
    }, {
        label: 30,
        value: 30
    }, {
        label: 'all',
        value: 0
    }],
});


app.mount('#app')

Date field global settings

You can globally set format for date field by passing dateFormats in the plugin options You can globally set mode for date field by passing dateMode in the plugin options (one of date , dateTime, time by default is dateTime)

const app = createApp(App);
app.use(ViGridBuilderPlugin, {

    dateFormats: {
        time: 'HH:mm',
        date: "yyyy-MM-dd",
        dateTime: "yyyy-MM-dd HH:mm:ss"
    },
    dateMode: 'date'
});

Css variables and global overwriting of the variables

| name | usage | default value
|------------------------------|---------------------------------------------------------------------|-----------------------| | --vi-grid-primary-color | background color of header and used as backgorund for rows on hover | rgba(0, 0, 255, 0.65) | --vi-grid-primary-text_color | text color of header and used as text color for rows on hover | rgb(255, 255, 255)
| --vi-grid-secondary-color | background color even rows in stripped table | rgb(243, 243, 243)
| --vi-grid-text-color | color of text in tabel body cells | rgb(0, 0, 0)
| --vi-grid-color | background color for table | rgb(255, 255, 255)

You can override this values in the options when plugin is installed:

const app = createApp(App);
app.use(ViGridBuilderPlugin, {
    style:
        {
            'color': 'white',
            'text-color': 'black',
            'secondary-color': 'lightgrey',
            'primary-color': '#f18080',
            'primary-text-color': 'white',
        }
})

Steps for adding changes for contributors

• git pull origin main
• add and test your changes in playground
• change the version in package.json
• vite build
• push to git
• npm publish