vTable

An 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">



!Example Table

---

Installation

Install via npm or yarn:

`bash
npm install @uniquedj95/vtable


OR


yarn add @uniquedj95/vtable
``

---

Usage

$3

`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


`

$3

`html



`

> Note: You must manually import styles from @uniquedj95/vtable/dist/lib/datatable.css.

---

API Reference

$3

| 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) |
| path | Yes | The key used to map row data to this column (e.g. first_name) |
| exportable | No | If true, values in this column can be exported (default: true) |
| initialSort | No | If true, this column is used for initial sorting (default: false) |
| sortable | No | If true, this column can be sorted (default: true) |
| initialSortOrder | No | Initial sort order: "asc", "desc", or "none" (requires initialSort) |
| sortCaseSensitive | No | If true, sorting is case sensitive (default: false) |
| drillable | No | If true, column data can be drilled (default: false) |
| 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 | |
| color | No | String | Button color (default: primary) |
| action | Yes | Function | Click handler. Receives activeRows, 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" |
| icon | No | ionicon | Icon string. If both label and icon are defined, icon is used |
| color | No | String | Button color (default: primary) |
| default | No | Boolean | If true, button listens to whole row clicks (default: false) |
| condition | No | Function | Returns boolean to show/hide the button (default: () => true) |
| 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" |
| 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 select 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 |

---

$3

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 |

---

$3

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 value
- max: 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

---

Examples

$3

`vue



`

$3

`vue



`

$3

`vue

`

$3

`vue

`

$3

`vue



`

$3

`vue



`

$3

`vue



`

---

Development

This project uses modern development tools to ensure code quality and consistency:

$3

`bash


Install dependencies

npm install

Run tests

npm test

Watch mode for development

npm run test:watch

Build the project

npm run build
`

$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 fixing

Formatting

npm run format # Format all files with Prettier
npm run format:check # Check if files are formatted correctly

Testing

npm test # Run all tests
npm run test:watch # Run tests in watch mode
npm run test:ui # Run tests with UI

Building

npm run build # Build the project for production
`

$3

This project follows Conventional Commits. Use the following format:

`
type(scope): description

Examples:


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.

---

Contribution

Contributions are welcome! Please open issues or submit pull requests for improvements, bug fixes, or new features.

---

License

MIT