Skip to content

Adapters.md

Latest commit

 

History

History
163 lines (118 loc) · 4.76 KB

Adapters.md

File metadata and controls

163 lines (118 loc) · 4.76 KB
Raw

Adapter Setup Reference

Entry Points

Adapter Import path Extra host styles
Shadcn default data-table-pro none beyond host shadcn/theme tokens
HeroUI data-table-pro/heroui @heroui/styles
The Gridcn data-table-pro/thegridcn host The Gridcn theme/token CSS
Shadcn virtual data-table-pro/virtual none beyond host shadcn/theme tokens
HeroUI virtual data-table-pro/heroui/virtual @heroui/styles
The Gridcn virtual data-table-pro/thegridcn/virtual host The Gridcn theme/token CSS

Base entrypoints are recommended when virtualization is disabled or toggled occasionally: the virtual implementation is then an on-demand chunk. Use the matching /virtual path when virtual rows/cards are part of the initial route and should load eagerly.

Required Imports

Shadcn default

@import "tailwindcss";
@import "data-table-pro/styles.css";

HeroUI

@import "tailwindcss";
@import "@heroui/styles";
@import "data-table-pro/styles.css";

The HeroUI adapter adds a .dtp-heroui root class and supplies HeroUI slot classes for table containers, dividers, fields, muted text, pagination, empty states, dropdowns, and tooltips. It does not require shadcn-style tokens such as --border, --card, --input, or --muted.

The host app should install @heroui/styles itself. data-table-pro only references that stylesheet in documentation and does not bundle it for consumers.

Override HeroUI slot styling in the host app only if you want a different visual treatment:

.dtp-heroui {
  --separator: color-mix(in oklch, var(--accent) 45%, transparent);
}

The Gridcn

@import "tailwindcss";
@import "data-table-pro/styles.css";
@import "./thegridcn-theme.css";

Styling Ownership

  • data-table-pro/styles.css owns package scanning and table container-query helpers.
  • The host app owns theme tokens and global visual language.
  • The package does not ship shadcn theme tokens.
  • The package does not ship HeroUI theme tokens.
  • The package does not ship The Gridcn theme tokens.

Adapter Class Hooks

Adapter implementations can override specific table surfaces through ui.classNames.

Compact toolbar icon buttons now have a dedicated hook:

  • toolbarCompactIconButton: applied to compact toolbar icon controls such as the collapsed search trigger, options button, view toggle buttons, icon-only selection actions, and icon-only/collapsed toolbar actions

Example:

classNames: {
  ...shadcnUiKit.classNames,
  toolbarCompactIconButton: "size-8",
}

Use that hook when a host design system wants compact toolbar icon buttons to be larger or smaller than the package defaults without targeting toolbar DOM structure directly.

Custom Adapter Factories

Use the stable adapter-authoring entrypoint instead of broad advanced internals:

import {
  createDataTable,
  primitiveUiKit,
  type DataTableUiKit,
} from "data-table-pro/adapter";

const customUiKit: DataTableUiKit = {
  ...primitiveUiKit,
  // Replace primitives and class-name slots owned by the host design system.
};

export const DataTable = createDataTable(customUiKit);

For an eager-virtual custom adapter, import createVirtualDataTable from data-table-pro/adapter/virtual. Keeping the factories separate prevents non-virtual adapters from statically reaching TanStack Virtual.

Full-Height Layout

DataTable defaults to flexGrow={true}. Put it in a constrained flex content region and let the package handle internal sizing:

<main className="flex h-full min-h-0 flex-col">
  <section className="flex min-h-0 flex-1 flex-col">
    <DataTable flexGrow />
  </section>
</main>

One host layout constraint remains: an ancestor still needs to establish the actual height boundary with h-full, h-screen, or a fixed-height container plus min-h-0.

Card mode supports explicit grid density without targeting internals:

<DataTable
  viewMode="card"
  cardRenderer={renderCard}
  cardGridClassName="grid-cols-2 @min-[640px]/data-table:grid-cols-3 @min-[768px]/data-table:grid-cols-4 @min-[1024px]/data-table:grid-cols-5 @min-[1280px]/data-table:grid-cols-6"
/>

Known Non-Goals

  • no runtime adapter prop
  • no mixed-library provider that swaps adapters dynamically
  • no bundled The Gridcn registry installer flow
  • no package-owned app theme
  • no The Gridcn 3D/showcase components

Recommended globals.css order

Shadcn default

@import "tailwindcss";
@import "data-table-pro/styles.css";

HeroUI

@import "tailwindcss";
@import "@heroui/styles";
@import "data-table-pro/styles.css";

No shadcn token aliases are required for the HeroUI adapter.

The Gridcn

@import "tailwindcss";
@import "data-table-pro/styles.css";
@import "./thegridcn-theme.css";