Dynamic Table

Usage

The simplest usage of can be shown in the following example:

To achieve the above the following code needs do be inserted in your Markdown text.

::ShDynamicTable
---
dataUrl: "http://dummyjson.com/users"
dataField: "users"
columns:
  - name: "firstName"
    title: "First Name"
    filter: false
    query: true
    sortable: true
    type: text
  - name: "lastName"
    title: "Last Name"
    filter: false
    query: true
    sortable: true
    type: text
  - name: "username"
    title: "username"
    filter: false
    query: true
    sortable: true
    type: text
  - name: "email"
    title: "Email"
    filter: false
    query: true
    sortable: false
    type: email
  - name: "gender"
    title: "Gender"
    filter: true
    sortable: true
    order: true
    type: text
  - name: "birthDate"
    title: "Birth Date"
    filter: false
    query: true
    sortable: true
    type: date
  - name: "age"
    title: "Age"
    filter: true
    query: true
    sortable: true
    type: number
ui:
  footer: "text-sm"
header: Dymanic Table example
footer: "*Copyright © 2024*"
---
::

The important parts are the dataUrl, and columns. The prior one define the URL from witch the data will be fetched. On the other hand, columns represent a list of elements where each table column is described.

Each column is described using the following properties:

• name - the property name
• title - the label that will be show in the column header
• filter - true | false value indication that if the field in question should be used for quick filters
• query - true | false value indicating if this filed should be used in query search
• sortable - true | false value indication if this field should be used for ordering the data
• type - one of the following [text, number, date] values defining the type of the field value

Beside the above the dataField parameter can be used if the data fetched holds the table items under a specific property. This is typical in REST API results. You can review the one used in above example where the items that we would like to show in the table is stored in users field.

Properties

Config

These style properties can be modified via ui and are stored in the .ts file:

export default {
  wrapper: "bg-gray-50 dark:bg-inherit border-2 border-neutral-200 dark:border-neutral-500 rounded-2xl p-5",
  header: "font-semibold text-center bg-slate-200 dark:bg-slate-700 dark:text-slate-200",
  base: "",
  footer: "font-semibold text-center bg-slate-200 dark:bg-slate-700 dark:text-slate-200",
  search: "pb-4",
  filter:  "",
  tableContainer: 'w-full my-8 max-h-[38rem] overflow-x-auto overflow-y-auto',
  table: 'min-w-full my-0 divide-y divide-gray-300 dark:divide-gray-700',
  tbody: 'divide-y divide-gray-300 dark:divide-gray-700',
  thead: "",
  tr: {
    base: '',
    selected: 'bg-oma-blue-400 hover:bg-oma-blue-300 text-white dark:bg-oma-blue-600 dark:hover:bg-oma-blue-500 dark:text-golden',
    active: 'hover:bg-neutral-200 dark:hover:bg-neutral-600 cursor-pointer'
  },
  th: {
    base: 'sticky top-0 z-10 text-left rtl:text-right bg-gray-50 dark:bg-neutral-600 shadow-[inset_0_-1px_0_theme(colors.gray.300)] dark:shadow-[inset_0_-1px_0_theme(colors.gray.700)]',
    padding: 'px-4 py-3.5',
    color: 'text-gray-900 dark:text-white',
    font: 'font-semibold',
    size: 'text-sm'
  },
  td: {
    base: 'whitespace-nowrap text-pretty ',
    padding: 'px-4 py-4',
    color: 'text-gray-500 dark:text-gray-400',
    font: '',
    size: 'text-sm'
  },
  pagination: '',
  perPage: [10, 25, 50, 100],
  default: {
    perPage: 10,
    sortAscIcon: 'i-heroicons-bars-arrow-up-20-solid',
    sortDescIcon: 'i-heroicons-bars-arrow-down-20-solid',
    sortButton: {
      icon: 'i-heroicons-arrows-up-down-20-solid',
      trailing: true,
      square: true,
      color: 'gray' as const,
      variant: 'ghost' as const,
      class: '-m-1.5 font-semibold text-sm'
    },
  }
}

Class Descriptions

These represent the class values utilized in the component. These values are customizable and can be strengthened or overridden through the ui properties' attributes.

wrapper

• Value: "bg-gray-50 dark:bg-inherit border-2 border-neutral-200 dark:border-neutral-500 rounded-2xl p-5"
• Description: Defines the overall container styles. The value "bg-gray-50 dark:bg-inherit border-2 border-neutral-200 dark:border-neutral-500 rounded-2xl p-5" applies a light background (bg-gray-50), inherits background color in dark mode (dark:bg-inherit), adds a 2-unit border (border-2), adjusts border color for dark mode (dark:border-neutral-500), rounds corners (rounded-2xl), and adds padding of 5 units (p-5).

header

• Value: "font-semibold text-center bg-slate-200 dark:bg-slate-700 dark:text-slate-200"
• Description: Styles the header section. The value "font-semibold text-center bg-slate-200 dark:bg-slate-700 dark:text-slate-200" sets a semi-bold font weight (font-semibold), centers the text (text-center), applies a light slate background (bg-slate-200), adjusts background color for dark mode (dark:bg-slate-700), and changes text color for dark mode (dark:text-slate-200).

base

• Value: ""
• Description: Serves as a base for custom styles, currently left empty for flexibility.

footer

• Value: "font-semibold text-center bg-slate-200 dark:bg-slate-700 dark:text-slate-200"
• Description: Defines styles for the footer. Similar to the header, the value sets a semi-bold font weight (font-semibold), centers text (text-center), applies a slate background (bg-slate-200), and adapts colors for dark mode (dark:bg-slate-700, dark:text-slate-200).

search

• Value: "pb-4"
• Description: Adds padding to the bottom of the search section. The value "pb-4" applies 4 units of bottom padding.

filter

• Value: ""
• Description: Provides a base for filter-specific styles, currently left empty for customization.

tableContainer

• Value: "w-full my-8 max-h-[38rem] overflow-x-auto overflow-y-auto"
• Description: Styles the scrollable box the table sits in. The value spans the full width (w-full), spaces it from the surrounding content (my-8), caps the height at a header plus ten single-line rows (max-h-38rem) and scrolls both ways inside that box (overflow-x-auto, overflow-y-auto), so page sizes above 10 rows scroll within the component instead of stretching the page past the viewport. Tables whose rows wrap onto several lines fit proportionally fewer rows in the same box. Raise or lower max-h-[38rem] through the ui property to show more or fewer rows before scrolling.

table

• Value: "min-w-full my-0 divide-y divide-gray-300 dark:divide-gray-700"
• Description: Styles the table itself. The value "min-w-full my-0 divide-y divide-gray-300 dark:divide-gray-700" ensures the table spans the full width (min-w-full), drops the prose margin so it does not take up room inside the scrolling container (my-0, the spacing lives on tableContainer instead), adds horizontal dividers (divide-y), and adjusts divider color for dark mode (dark:divide-gray-700).

tbody

• Value: "divide-y divide-gray-300 dark:divide-gray-700"
• Description: Styles the table body. The value adds horizontal dividers (divide-y), with adjustments for light and dark mode (divide-gray-300, dark:divide-gray-700).

thead

• Value: ""
• Description: A placeholder for header-specific styles, currently left empty for customization.

tr

• Base:
  • Value: ""
  • Description: Base styles for table rows, currently left empty.
• Selected:
  • Value: "bg-oma-blue-400 hover:bg-oma-blue-300 text-white dark:bg-oma-blue-600 dark:hover:bg-oma-blue-500 dark:text-golden"
  • Description: Applies styles for selected rows. Includes a blue background (bg-oma-blue-400), hover effect (hover:bg-oma-blue-300), white text color (text-white), and dark mode adaptations (dark:bg-oma-blue-600, dark:hover:bg-oma-blue-500, dark:text-golden).
• Active:
  • Value: "hover:bg-neutral-200 dark:hover:bg-neutral-600 cursor-pointer"
  • Description: Adds hover effects and pointer cursor. The value changes the background on hover (hover:bg-neutral-200, dark:hover:bg-neutral-600) and sets the cursor to pointer (cursor-pointer).

th

• Base:
  • Value: "sticky top-0 z-10 text-left rtl:text-right bg-gray-50 dark:bg-neutral-600 shadow-[inset_0_-1px_0_theme(colors.gray.300)] dark:shadow-[inset_0_-1px_0_theme(colors.gray.700)]"
  • Description: Pins the column titles to the top of the scrolling table container (sticky, top-0, z-10), sets text alignment (text-left, rtl:text-right), applies an opaque background so rows do not show through while scrolling (bg-gray-50, dark:bg-neutral-600), and draws the divider under the header with an inset box shadow (the border of a sticky header is dropped by the table's collapsed borders).
• Padding:
  • Value: "px-4 py-3.5"
  • Description: Adds padding of 4 units horizontally (px-4) and 3.5 units vertically (py-3.5).
• Color:
  • Value: "text-gray-900 dark:text-white"
  • Description: Defines text colors for light and dark modes.
• Font:
  • Value: "font-semibold"
  • Description: Sets a semi-bold font weight.
• Size:
  • Value: "text-sm"
  • Description: Defines the font size as small (text-sm).

td

• Base:
  • Value: "whitespace-nowrap text-pretty"
  • Description: Ensures text does not wrap (whitespace-nowrap) and applies a custom style class (text-pretty).
• Padding:
  • Value: "px-4 py-4"
  • Description: Adds padding of 4 units both horizontally and vertically.
• Color:
  • Value: "text-gray-500 dark:text-gray-400"
  • Description: Sets text colors for light and dark modes.
• Font:
  • Value: ""
  • Description: Placeholder for custom font styles.
• Size:
  • Value: "text-sm"
  • Description: Defines the font size as small (text-sm).

pagination

• Value: ""
• Description: Placeholder for pagination-specific styles.

perPage

• Value: [10, 25, 50, 100]
• Description: Defines available options for items per page.

default

• Value: An object containing default configuration:
  • perPage: 10
  • sortAscIcon: 'i-heroicons-bars-arrow-up-20-solid'
  • sortDescIcon: 'i-heroicons-bars-arrow-down-20-solid'
  • sortButton:
    • icon: 'i-heroicons-arrows-up-down-20-solid'
    • trailing: true
    • square: true
    • color: 'gray'
    • variant: 'ghost'
    • class: '-m-1.5 font-semibold text-sm'
• Description: Holds default configuration values for pagination and sorting icons, with button styles defined by "sortButton" properties.