An advanced datatable for Ionic vue framework
npm install @uniquedj95/vtableAn advanced data table component for the Ionic Vue framework, offering powerful features for data display, manipulation, and interaction.
```vue`="https://badgen.net/badge/Typescript/4.x/yellow" alt="TS">
---
Install via npm or yarn:
`bash``
npm install @uniquedj95/vtableOR
yarn add @uniquedj95/vtable
---
`typescript
// src/main.ts
import { VTable } from '@uniquedj95/vtable';
// Import datatable CSS
import '@uniquedj95/vtable/dist/lib/datatable.css';
const app = createApp(App).use(IonicVue).use(VTable).use(router);
router.isReady().then(() => {
app.mount('#app');
});
`
`html`
`html
`
> Note: You must manually import styles from @uniquedj95/vtable/dist/lib/datatable.css.
---
| Prop Name | Default Value | Description |
| ---------------- | ------------- | --------------------------------------------------------------------- |
| rows | [ ] | List of data objects mapped into table rows |
| asyncRows | undefined | A promise function that returns a list of data |
| columns | [ ] | List of table column definitions |
| actionButtons | [ ] | List of buttons for global table actions |
| rowActionButtons | [ ] | List of buttons for actions affecting specific rows |
| customFilters | [ ] | List of custom filters affecting the data source |
| color | undefined | Color theme for the datatable. Accepted: primary, secondary, etc. |
| config | undefined | Configuration object affecting datatable behavior |
#### 1.1 Table Column
A table column is defined with the following properties:
| Property Name | Required | Description |
| ----------------- | -------- | ------------------------------------------------------------------------------ |
| label | Yes | The column heading text (e.g. First Name) |first_name
| path | Yes | The key used to map row data to this column (e.g. ) |true
| exportable | No | If true, values in this column can be exported (default: ) |false
| initialSort | No | If true, this column is used for initial sorting (default: ) |true
| sortable | No | If true, this column can be sorted (default: ) |"asc"
| initialSortOrder | No | Initial sort order: , "desc", or "none" (requires initialSort) |false
| sortCaseSensitive | No | If true, sorting is case sensitive (default: ) |false
| drillable | No | If true, column data can be drilled (default: ) |
| preSort | No | Function to process values before sorting |
| formatter | No | Function to format values for display (HTML content auto-detected & sanitized) |
| thStyles | No | CSS styles for table header cell |
| thClasses | No | CSS classes for table header cell |
| tdStyles | No | CSS styles for table data cells (can be function for dynamic styles) |
| tdClasses | No | CSS classes for table data cells (can be function for dynamic classes) |
| customRenderer | No | Function to completely customize cell content rendering |
| slotName | No | Name of Vue slot to use for custom cell content |
| component | No | Vue component to render in the cell |
| componentProps | No | Function returning props for the Vue component |
##### 1.1.1 Advanced Column Formatting
vtable provides multiple ways to format and style column data, giving you complete control over presentation:
Dynamic Styles and Classes:
`typescript`
{
label: 'Score',
path: 'score',
tdStyles: (value, row) => ({
color: value >= 80 ? 'green' : value >= 60 ? 'orange' : 'red',
fontWeight: 'bold'
}),
tdClasses: (value, row) => [
'score-cell',
value >= 80 ? 'high-score' : 'low-score'
]
}
Custom Renderers:
`typescript
import { renderStatus, renderChipList, renderProgress } from '@uniquedj95/vtable';
// Status with colored chips
{
label: 'Status',
path: 'status',
customRenderer: (value, row, column) => {
const statusConfig = {
active: { color: 'success', label: 'Active' },
inactive: { color: 'danger', label: 'Inactive' },
pending: { color: 'warning', label: 'Pending' }
};
return renderStatus(value, statusConfig);
}
}
// Progress bar
{
label: 'Progress',
path: 'progress',
customRenderer: (value) => {
const color = value >= 80 ? 'success' : value >= 50 ? 'warning' : 'danger';
return renderProgress(value, 100, color);
}
}
// Multiple tags as chips
{
label: 'Tags',
path: 'tags',
customRenderer: (value) => {
return renderChipList(value, { color: 'primary', outline: true }, 3);
}
}
`
Vue Slots:
`typescript`
// Column definition
{
label: 'Actions',
path: 'id',
slotName: 'actions',
sortable: false
}
`vue`
HTML Content (Auto-detected):
``typescript`
HTML Content (Auto-detected & Sanitized):typescript``
{
label: 'Description',
path: 'description',
formatter: (value) => {
// HTML content is automatically detected, sanitized, and rendered safely
return value.replace(
/(important|urgent)/gi,
'$1'
);
}
}
``
Vue Components:
`typescript
import CustomRating from './CustomRating.vue';
{
label: 'Rating',
path: 'rating',
component: CustomRating,
componentProps: (value, row) => ({ rating: value, maxStars: 5 })
}
``
#### 1.2 Action Button
Action buttons are displayed above the table and affect the entire table. Each action button has the following properties:
| Property Name | Required | Type | Description |
| ------------- | -------- | -------- | ------------------------------------------------------------------------- | --- |
| label | Yes | String | Button label (e.g. Submit) | |
| icon | No | ionicons | Icon displayed with the label, separated by |primary
| color | No | String | Button color (default: ) |activeRows
| action | Yes | Function | Click handler. Receives , allRows, filters, and columns |
#### 1.3 Row Action Button
Row action buttons are attached to each row for row-specific actions. Each button has the following properties:
| Property Name | Required | Type | Description |
| ------------- | -------- | -------- | ------------------------------------------------------------------------ |
| label | No | String | Button label. If both label and icon are missing, defaults to "Button" |primary
| icon | No | ionicon | Icon string. If both label and icon are defined, icon is used |
| color | No | String | Button color (default: ) |false
| default | No | Boolean | If true, button listens to whole row clicks (default: ) |() => true
| condition | No | Function | Returns boolean to show/hide the button (default: ) |
| action | Yes | Function | Click handler. Receives row data and its index |
#### 1.4 Custom Filter
Custom filters are used when fetching data from the source/API. Each filter has the following properties:
| Property Name | Required | Type | Description |
| ------------- | -------- | -------- | -------------------------------------------------- | -------- | ------ | -------- | ------------ |
| id | Yes | String | Unique identifier for the filter |
| label | No | String | Filter input label |
| value | No | any | Default value for the filter |
| gridSize | No | Number | Column grid size (1-12) |
| type | Yes | String | Filter input type: "text" | "number" | "date" | "select" | "dateRange" |select
| options | No | Array | Options for select input filters |
| placeholder | No | String | Placeholder text when no value is set |
| required | No | Boolean | If true, filter must be set before emitting events |
| multiple | No | Boolean | For type: allows multiple selection |
| onUpdate | No | Function | Callback when filter value changes |
| slotName | No | String | Used for defining named slots for advanced filters |
##### 1.4.1 Filter Option
A filter option object has the following properties:
| Property Name | Required | Type | Description |
| ------------- | -------- | ------------- | --------------------------------------------------- |
| label | Yes | String | Option label |
| value | Yes | String/Number | Option value |
| isChecked | No | Boolean | If true, option is selected (for checkboxes/radios) |
| other | No | any | Any additional data |
#### 1.5 Table Config
General configuration options for the datatable:
| Property Name | Required | Type | Default | Description |
| ---------------- | -------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| showSubmitButton | No | Boolean | false | Show/hide submit button for custom filters. If enabled, filter changes are not emitted until submit is pressed. |
| showSearchField | No | Boolean | true | Show/hide the search input field. If disabled, search is hidden even if data is available. |
| showIndices | No | Boolean | false | Show/hide index numbers column |
---
The data table emits the following events:
| Event Name | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| customFilter | Emitted when the submit button is clicked and all required filters are set. If showSubmitButton is false, emitted whenever a filter changes. |
| drilldown | Emitted when a drillable cell is clicked |
---
vtable includes ready-to-use cell formatting components accessible via the utils export:
`typescript`
import {
renderStatus,
renderChip,
renderBadge,
renderChipList,
renderProgress,
renderBoolean,
renderHtml,
} from '@uniquedj95/vtable';
#### 3.1 Available Components
renderStatus(value, statusConfig, defaultConfig?)
- Renders status values with predefined colors and styles
- statusConfig: Object mapping status values to { color, label?, outline? }
renderChip(value, config?, onClick?)
- Renders a single chip component
- config: { color?, outline?, size? }
renderBadge(value, config?)
- Renders a badge component
- config: { color?, size? }
renderChipList(values, config?, maxVisible?)
- Renders an array of values as chips with overflow handling
- Shows a "+X" chip when there are more items than maxVisible
renderProgress(value, max?, color?)
- Renders a progress bar
- value: Current progress valuemax
- : Maximum value (default: 100)color
- : Ionic color (default: 'primary')
renderBoolean(value, trueConfig?, falseConfig?)
- Renders boolean values as colored badges
- trueConfig/falseConfig: { color, label }
renderHtml(htmlContent)
- Safely renders HTML content with automatic sanitization
- Removes dangerous elements (script, iframe, etc.) and event handlers
- Use only with trusted or validated content
- Safely renders HTML content
---
`vue
`
`vue
`
`vue`
`vue`
`vue
`
`vue
`
`vue
:columns="columns"
:customFilters="filters"
@customFilter="onFilter"
/>
`
---
This project uses modern development tools to ensure code quality and consistency:
`bashInstall dependencies
npm install
$3
- ESLint: Linting and code quality checks
- Prettier: Code formatting
- Husky: Git hooks automation
- Commitlint: Conventional commit message validation
- Lint-staged: Run linters on staged files only
$3
`bash
Linting
npm run lint # Lint and auto-fix issues
npm run lint:check # Check for lint issues without fixingFormatting
npm run format # Format all files with Prettier
npm run format:check # Check if files are formatted correctlyTesting
npm test # Run all tests
npm run test:watch # Run tests in watch mode
npm run test:ui # Run tests with UIBuilding
npm run build # Build the project for production
`$3
This project follows Conventional Commits. Use the following format:
`
type(scope): descriptionExamples:
feat: add new filtering feature
fix: resolve pagination bug
docs: update API documentation
refactor: improve table rendering performance
``For more details on development standards, see CODE_STANDARDS.md.
---
Contributions are welcome! Please open issues or submit pull requests for improvements, bug fixes, or new features.
---