Documentation

Complete guide to integrating beautiful, accessible data tables using the TableOne API.

Introduction

TableOne is a table rendering API service that generates beautiful, fully-functional data tables that you can embed in your application using iframes. No installation, no dependencies, no frontend code required.

How it works: You provide a data source URL and configuration parameters, TableOne renders a complete table with pagination, search, sorting, and actions - all via a simple iframe.

Key Benefits

  • Zero Installation: No npm packages, no build steps, just an iframe
  • Framework Agnostic: Works with any backend (Node.js, PHP, Python, Ruby, Rust, etc.)
  • Fully Rendered: Server-side rendering means instant load times
  • Responsive & Accessible: WCAG 2.1 AA compliant, mobile-friendly out of the box
  • Customizable: Control themes, pagination, search, and more via URL parameters

Quick Start

Get started in 3 simple steps:

1. Create a Data Endpoint

Your backend must expose an endpoint that returns JSON in the TableOne format:

GET /api/users

Response:
{
  "columns": [
    { "key": "id", "label": "ID", "sortable": true },
    { "key": "name", "label": "Name", "sortable": true },
    { "key": "status", "label": "Status", "type": "chip" }
  ],
  "rows": [
    { "id": 1, "name": "John Doe", "status": "Active" },
    { "id": 2, "name": "Jane Smith", "status": "Inactive" }
  ]
}

2. Embed the Table

Add an iframe pointing to the TableOne API with your data source:

<iframe 
  src="https://table-one-two.vercel.app/api/render-table?src=/api/users&pagination=true&theme=dark" 
  width="100%" 
  height="600" 
  style="border:none; border-radius:12px;"
></iframe>

3. Done!

That's it! TableOne will fetch your data and render a complete, interactive table.

Pro Tip: The src parameter should point to YOUR backend endpoint that returns the table data.

API Endpoint

The TableOne rendering service is available at:

https://table-one-two.vercel.app/api/render-table
Production: Replace localhost:3000 with your production TableOne API URL.

Required Parameters

Parameter Description Example
src URL to your data endpoint (relative or absolute) /api/users

Optional Parameters

Customize the table behavior with these URL parameters:

Parameter Values Default Description
pagination true/false false Enable pagination controls
pagination-type simple/numeric simple Pagination style
page-size number 5 Rows per page
theme default/dark default Visual theme
search true/false false Enable search input
search-mode frontend/backend frontend Search mode
radius CSS value 16px Border radius

Complete Example

<iframe 
  src="https://table-one-two.vercel.app/api/render-table?src=/api/users&pagination=true&pagination-type=numeric&page-size=10&theme=dark&search=true" 
  width="100%" 
  height="600" 
  style="border:none; border-radius:12px;"
></iframe>

Data Structure

TableOne expects data in a specific JSON format with columns and rows:

Column Definition

Property Type Required Description
key string Required Unique identifier for the column, matches row data keys
label string Required Display name for the column header
sortable boolean Optional Enable sorting for this column (default: false)
type string Optional Column type: 'chip', 'status', 'traffic-light', 'link'
config object Optional Configuration object for column type (e.g., variant mappings)

Row Definition

Each row is an object where keys match the column key values:

{
  "id": 1,
  "name": "Iron Man",
  "team": "Avengers",
  "status": "Active",
  "actions": [
    { "label": "Edit", "action": "edit", "icon": "ph-pencil-simple" },
    { "label": "Delete", "action": "delete", "icon": "ph-trash" }
  ]
}
Note: The actions property is special and will render action buttons in a separate column.

Integration Examples

TableOne works with any backend language. Here are examples for popular frameworks:

Complete Data Example with Actions

Here's a complete example showing how your backend endpoint should return data with actions:

{
  "columns": [
    { "key": "id", "label": "ID", "sortable": true },
    { "key": "name", "label": "User", "sortable": true },
    { "key": "email", "label": "Email", "sortable": true },
    { "key": "role", "label": "Role", "type": "chip", 
      "config": { 
        "variants": {
          "Admin": "danger",
          "Editor": "warning",
          "Viewer": "neutral"
        }
      }
    },
    { "key": "status", "label": "Status", "type": "status" }
  ],
  "rows": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "role": "Admin",
      "status": "Active",
      "actions": [
        { "label": "Edit", "action": "edit", "icon": "ph-pencil-simple" },
        { "label": "Clone", "action": "clone", "icon": "ph-copy" },
        { "label": "Delete", "action": "delete", "icon": "ph-trash" }
      ]
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "Editor",
      "status": "Active",
      "actions": [
        { "label": "Edit", "action": "edit", "icon": "ph-pencil-simple" },
        { "label": "Clone", "action": "clone", "icon": "ph-copy" },
        { "label": "Delete", "action": "delete", "icon": "ph-trash" }
      ]
    },
    {
      "id": 3,
      "name": "Bob Wilson",
      "email": "bob@example.com",
      "role": "Viewer",
      "status": "Inactive",
      "actions": [
        { "label": "Edit", "action": "edit", "icon": "ph-pencil-simple" },
        { "label": "Clone", "action": "clone", "icon": "ph-copy" },
        { "label": "Delete", "action": "delete", "icon": "ph-trash" }
      ]
    }
  ]
}

Column Types

TableOne supports several column types for rich data visualization:

Chip

Display values as colored badges/chips:

{
  "key": "role",
  "label": "Role",
  "type": "chip",
  "config": {
    "variants": {
      "Admin": "danger",
      "Editor": "warning",
      "Viewer": "neutral"
    }
  }
}

Available variants: success, warning, danger, info, neutral

Status / Traffic Light

Display status with colored dots:

{
  "key": "status",
  "label": "Status",
  "type": "status"
}

Link

Render values as clickable links:

{
  "key": "website",
  "label": "Website",
  "type": "link"
}
Auto-mapping: If no explicit variant mapping is provided, TableOne automatically assigns colors based on keywords like "active", "pending", "failed", etc.

Row Actions

Add action buttons to each row using the actions property:

"actions": [
  {
    "label": "Edit",
    "action": "edit",
    "icon": "ph-pencil-simple"
  },
  {
    "label": "Delete",
    "action": "delete",
    "icon": "ph-trash"
  },
  {
    "label": "View Details",
    "action": "view",
    "icon": "ph-eye"
  }
]
Note: Actions are handled within the iframe. For custom behavior, you'll need to implement postMessage communication between the iframe and parent page.

Pagination

Enable pagination to handle large datasets by adding URL parameters:

Simple Pagination

<iframe 
  src="https://table-one-two.vercel.app/api/render-table?src=/api/users&pagination=true&page-size=10"
  width="100%" 
  height="600"
></iframe>

Numeric Pagination

<iframe 
  src="https://table-one-two.vercel.app/api/render-table?src=/api/users&pagination=true&pagination-type=numeric&page-size=25"
  width="100%" 
  height="600"
></iframe>

Add search functionality to filter table data:

Frontend Search

Filters data on the client side (inside the iframe):

<iframe 
  src="https://table-one-two.vercel.app/api/render-table?src=/api/users&search=true&search-mode=frontend"
  width="100%" 
  height="600"
></iframe>
Note: Frontend search works best for smaller datasets (< 1000 rows). For larger datasets, implement server-side filtering in your data endpoint.

Sorting

Enable sorting on specific columns by setting sortable: true in your column definition:

{
  "columns": [
    { "key": "name", "label": "Name", "sortable": true },
    { "key": "email", "label": "Email", "sortable": true },
    { "key": "role", "label": "Role", "sortable": false }
  ]
}

Users can click on sortable column headers to sort the data.

Themes

TableOne comes with built-in themes:

Default (Light)

<iframe 
  src="https://table-one-two.vercel.app/api/render-table?src=/api/users&theme=default"
  width="100%" 
  height="600"
></iframe>

Dark

<iframe 
  src="https://table-one-two.vercel.app/api/render-table?src=/api/users&theme=dark"
  width="100%" 
  height="600"
></iframe>

Backend Integration

Your backend must provide a JSON endpoint that returns data in the TableOne format:

{
  "columns": [
    { "key": "id", "label": "ID", "sortable": true },
    { "key": "name", "label": "Name", "sortable": true }
  ],
  "rows": [
    { "id": 1, "name": "John Doe" },
    { "id": 2, "name": "Jane Smith" }
  ]
}
Tip: Your endpoint can be dynamic and filter/paginate data server-side before returning it to TableOne.

Icons Reference

TableOne uses Phosphor Icons. Here are commonly used icons for actions:

Icon Class Usage Preview
ph-pencil-simple Edit action
ph-trash Delete action
ph-eye View/Preview action
ph-download-simple Download action
ph-copy Copy/Duplicate action
ph-share Share action
ph-gear Settings action
ph-info Info/Details action
ph-arrow-square-out External link action
ph-check-circle Approve action
ph-x-circle Reject action
ph-lock Lock/Restrict action

Browse the full icon library at phosphoricons.com

Pro Tip: You can use any Phosphor icon by using the class name format ph-{icon-name}