React Table Plus

A powerful and customizable React table component library with advanced features including avatars, multi-avatars, checkboxes, actions dropdown, and extensive styling options.

Table of Contents

• Features
• Installation & Usage
• Quick Start
• Feature Examples
  • Responsive Tables
  • Row Selection (Checkbox)
  • Single Avatar
  • Multi-Avatar (Team)
  • Actions Dropdown
  • Custom Styling
  • Loading State
  • Bonus Tip
• Advanced Examples
• Complete API Reference
  • Core Props
  • Feature Props
  • Configuration Interfaces
• Complete Styling Guide
  • Header & Title Styling
  • Table Body Styling
  • Row Styling
  • Avatar Styling
  • Multi-Avatar Styling
  • Actions Button Styling
  • Dropdown Menu Styling
  • Status Column Styling
• Styling Examples
  • Customize Table
  • Compact Mobile-Friendly Design
  • High Contrast Accessibility Theme
  • Corporate Brand Theme
• Props Deep Dive
• Live Demo
• Connect With Me

Features

• Responsive Tables - Fully responsive design that works on all devices
• Avatar Support - Display single or multiple user avatars in table cells
• Row Selection - Checkbox-based row selection with select all functionality
• Custom Styling - Complete customization using class and props.
• Actions Dropdown - Built-in actions menu with view, edit, and delete options
• Loading States - Built-in loading indicators and empty state handling
• Mobile Friendly - Optimized for mobile and tablet viewing
• TypeScript Ready - Full TypeScript support with comprehensive type definitions
• Theme change - Comprehensive theming system

Installation & Usage

npm install react-table-plus
# or
yarn add react-table-plus

Quick Start

Basic Usage

import React from 'react';
import TableComponent from 'react-table-plus';

const users = [
  { id: 1, name: 'John Doe', email: '[email protected]', role: 'Admin' },
  { id: 2, name: 'Jane Smith', email: '[email protected]', role: 'User' },
  { id: 3, name: 'Bob Johnson', email: '[email protected]', role: 'Editor' },
];

function UserTable() {
  return (
    <TableComponent
      column={['ID', 'Name', 'Email', 'Role']}
      data={users}
      Layout={['id', 'name', 'email', 'role']}
    />
  );
}

export default UserTable;

Feature Examples

Responsive Tables

Tables automatically adapt to screen size.

<TableComponent
  column={['ID', 'Name', 'Email', 'Role']}
  data={users}
  Layout={['id', 'name', 'email', 'role']}
/>

• On small screens, horizontal scroll appears
• No additional configuration needed

Row Selection (Checkbox)

Select rows individually or all at once.

const [selectedRows, setSelectedRows] = useState<number[]>([]);

<TableComponent
  column={['ID', 'Name', 'Email']}
  data={users}
  Layout={['id', 'name', 'email']}
  checkbox={{ selectedRows, setSelectedRows }}
/>

Extra Tips:

• Use checkedRows to get selected rows
• Supports “Select All” automatically in header

Single Avatar

Display a profile picture with optional title and subtitle.

<TableComponent
  column={['Name', 'Email', 'Avatar']}
  data={[{ id: 1, name: 'John Doe', email: '[email protected]', avatar: 'https://i.pravatar.cc/150?img=1' }]}
  Layout={['name', 'email', 'avatar']}
  avatar={{ column: 2, imgUrl: 'avatar', title: 'name', subtitle: 'email' }}
/>

Extra Tips:

• Tooltip shows title
• Subtitle can display email, role, or status

Multi-Avatar (Team)

Display multiple avatars in one table cell for groups or teams.

<TableComponent
  column={['Project', 'Team']}
  data={[
    {
      project: 'Website Redesign',
      team: [
        { name: 'Alice', avatar: 'url1' },
        { name: 'Bob', avatar: 'url2' }
      ]
    }
  ]}
  Layout={['project', 'team']}
  multiAvatar={{ column: 1, imgArray: 'team', imgUrl: 'avatar', name: 'name' }}
/>

Extra Tips:

• Hover over each avatar shows member name
• Supports any number of avatars

Actions Dropdown

Add row-level actions (view, edit, delete, custom navigation).

<TableComponent
  column={['ID', 'Name', 'Actions']}
  data={[{ _id: 1, name: 'John Doe' }]}
  Layout={['id', 'name']}
  actions={{
    view: '/details',
    edit: '/edit',
    delete: (id) => alert(`Deleted ${id}`),
    onNavigate: (path) => navigate(path),
  }}
/>

// Use idkey if row id field is different
actions={{
  idkey: '_id'
}}

Extra Tips:

• Use idkey if row id field is different
• Dropdown styling can be customized with styles

Custom Styling

Change colors, fonts, row hover, and status badges.

<TableComponent
  column={['Name', 'Status']}
  data={[{ name: 'John Doe', status: 'Active' }]}
  Layout={['name', 'status']}
  styles={{
    HeaderBg: '#f3f4f6',
    RowHoverColor: '#e5e7eb',
    TitleFontStyle: 'bold',
    StatusBgColor: '#10b981',
    StatusTextColor: '#fff',
  }}
/>

Extra Tips:

• Full control over header, rows, avatars, dropdowns, and status
• Supports multiple pre-built themes or corporate colors

Loading State

Show a loading spinner while fetching data.

<TableComponent
  column={['Name', 'Email']}
  data={[]}
  Layout={['name', 'email']}
  loading={true}
/>

• Automatically displays spinner
• No rows are rendered during loading

Bonus Tip

If you want to use nextjs router, just do this:

const router = useRouter();
...
onNavigate: (path) => router.push(path),

or if you are using react-router-dom then do this:

import { useNavigate } from "react-router-dom";

const navigate = useNavigate();
...
onNavigate: (path) => navigate(path),

Also, navigation can be handled with functions.

Advanced Examples

Combine avatars, multi-avatar, checkbox, actions, and custom styling:

<TableComponent
  column={['ID', 'Project', 'Team', 'Status', 'Priority']}
  data={projects}
  Layout={['id', 'name', 'team', 'status.name', 'priority']}
  avatar={{ column: 1, imgUrl: 'avatar', title: 'name' }}
  multiAvatar={{ column: 2, imgArray: 'team', imgUrl: 'avatar', name: 'name' }}
  checkbox={{ selectedRows, setSelectedRows }}
  actions={{
    view: '/details',
    edit: '/edit',
    delete: (id) => alert(`Deleted ${id}`),
    onNavigate: (path) => navigate(path),
  }}
  styles={{
    HeaderBg: '#f8fafc',
    RowHoverColor: '#f1f5f9',
    StatusBgColor: '#10b981',
    StatusTextColor: '#fff',
    ActionsButtonBg: '#e2e8f0',
    TitleFontStyle: 'bold',
  }}
/>

Extra Tips:

• Fully responsive on all devices
• Combine with loading prop for async data
• Works with nested object data using dot notation in Layout

Complete API Reference

Core Props

column (required)

• Type: string[]
• Description: Defines the column headers that will be displayed in the table
• Usage: ['ID', 'Name', 'Email', 'Status']
• Note: Must correspond to the Layout array

data (required)

• Type: any[]
• Description: Array of data objects that will be rendered as table rows
• Usage:

const users = [
  { id: 1, name: 'John', email: '[email protected]', status: 'Active' },
  { id: 2, name: 'Jane', email: '[email protected]', status: 'Inactive' }
];

Layout (required)

• Type: string[]
• Description: Maps column headers to object properties using dot notation for nested properties
• Usage: ['id', 'name', 'email', 'status'] or ['id', 'user.name', 'user.email']
• Note: Must have same length as column array

Feature Props

avatar (optional)

• Type: Avatar
• Description: Displays user avatars in a specified column
• Configuration:
  • column: Column index (0-based) where avatar appears
  • imgUrl: Property name containing avatar image URL
  • title: Property name for tooltip text (optional)
  • subtitle: Property name for subtitle text (optional)

multiAvatar (optional)

• Type: MultiAvatar
• Description: Displays multiple user avatars in a single cell
• Configuration:
  • column: Column index (0-based) where multi-avatars appear
  • imgArray: Property name containing array of user objects
  • imgUrl: Property name for avatar URL in each user object
  • name: Property name for tooltip text in each user object (optional)

actions (optional)

• Type: ActionProps
• Description: Adds a dropdown menu with actions for each row
• Configuration:
  • idkey: Property name for unique row ID (default: 'id')
  • view: Route path for view action (optional)
  • edit: Route path for edit action (optional)
  • delete: Delete handler function (optional)
  • onNavigate: Navigation handler function (optional)

checkbox (optional)

• Type: boolean
• Description: Enables row selection with checkboxes
• Usage: <TableComponent checkbox={{ selectedRows, setSelectedRows }} ... />
• Note: Requires checkedRows and setCheckedRows for controlled usage

checkedRows

• Type: number[]
• Description: Controlled array of selected row IDs
• Usage: [1, 3, 5] (row IDs that are selected)

setCheckedRows

• Type: (rows: number[]) => void
• Description: Callback function called when row selection changes
• Usage: (selectedIds) => setSelectedRows(selectedIds)

loading (optional)

• Type: boolean
• Description: Shows loading spinner instead of table content
• Usage: <TableComponent loading={isLoading} ... />

className (optional)

• Type: string
• Description: Additional CSS class applied to table wrapper
• Usage: <TableComponent className="my-custom-table" ... />

styles (optional)

• Type: StyleProps
• Description: Comprehensive styling configuration object
• Usage: See the Styling Guide below

Configuration Interfaces

Avatar Configuration

interface Avatar {
  column: number;        // Column index where avatar appears (0-based)
  imgUrl: string;        // Field name containing the avatar image URL
  title?: string;        // Field name for title text (optional)
  subtitle?: string;     // Field name for subtitle text (optional)
}

Multi-Avatar Configuration

interface MultiAvatar {
  column: number;        // Column index where multi-avatar appears (0-based)
  imgArray: string;      // Field name containing array of user objects
  imgUrl: string;        // Field name for avatar URL in each user object
  name?: string;         // Field name for name in each user object (for tooltips)
}

Actions Configuration

interface ActionProps {
  idkey?: string;        // Field name for unique ID (default: 'id')
  delete?: (id: string) => void;  // Delete handler function
  view?: string;         // View route path (e.g., '/details')
  edit?: string;         // Edit route path (e.g., '/edit')
  onNavigate?: (path: string) => void;  // Navigation handler function
}

Complete Styling Guide

The styles prop accepts a comprehensive configuration object that controls every visual aspect of the table. See below for a detailed breakdown.

Header & Title Styling

| Property | Type | Description | Example | |----------|------|-------------|---------| | TitleText | number | Font size for column headers (px) | 16 | | TitleFontStyle | "normal" | "bold" | "500" | "600" | Font weight for headers | "bold" | | TitleColor | string | Text color for column headers | "#1f2937" | | HeaderBg | string | Background color for header row | "#f8fafc" | | HeaderBorderColor | string | Border color for header | "#e5e7eb" | | TitleTextAlign | "start" | "center" | "end" | table title text style | "center" |

Table Body Styling

| Property | Type | Description | Example | |----------|------|-------------|---------| | TableBg | string | Background color for entire table | "#ffffff" | | TableBorderColor | string | Border color for table outline | "#e5e7eb" | | TextColor | string | Default text color for table content | "#1f2937" | | FontSize | number | Base font size for table content (px) | 14 |

Row Styling

| Property | Type | Description | Example | |----------|------|-------------|---------| | RowHeight | number | Height of each table row (px) | 50 | | TextAlign | "start" | "center" | "end" | text style | "center" | | RowBg | string | Default background color for rows | "#ffffff" | | RowHoverColor | string | Background color when hovering over rows | "f3f4f6" | | RowBorderColor | string | Border color between rows | "#e5e7eb" |

Avatar Styling

| Property | Type | Description | Example | |----------|------|-------------|---------| | AvatarSize | number | Width and height of avatar images (px) | 40 | | AvatarBorderRadius | string | Border radius for avatar images | "50%" |

Multi-Avatar Styling

| Property | Type | Description | Example | |----------|------|-------------|---------| | MultiAvatarSize | number | Size of each avatar in multi-avatar display (px) | 32 | | MultiAvatarBorder | string | Border style for multi-avatar images | "2px solid #fff" |

Actions Button Styling

| Property | Type | Description | Example | |----------|------|-------------|---------| | ActionsButtonBg | string | Background color for action buttons | "#e5e7eb" | | ActionsButtonColor | string | Text color for action buttons | "#111827" | | ActionsButtonHoverBg | string | Background color when hovering action buttons | "#d1d5db" |

Dropdown Menu Styling

| Property | Type | Description | Example | |----------|------|-------------|---------| | DropdownBg | string | Background color for dropdown menu | "#ffffff" | | DropdownBorderColor | string | Border color for dropdown menu | "#e5e7eb" | | DropdownItemBg | string | Background color for dropdown items | "#ffffff" | | DropdownItemHoverBg | string | Background color when hovering dropdown items | "#f3f4f6" |

Status Column Styling

| Property | Type | Description | Example | |----------|------|-------------|---------| | StatusTextColor | string | Text color for status indicators | "#ffffff" | | StatusBgColor | string | Background color for status indicators | "#10b981" |

Styling Examples

Customize Table

<TableComponent
  column={['Name', 'Email', 'Status']}
  data={users}
  Layout={['name', 'email', 'status']}
  styles={{
    // Dark header
    HeaderBg: '#1f2937',
    TitleColor: '#f9fafb',
    HeaderBorderColor: '#374151',
    // Dark table
    TableBg: '#111827',
    TableBorderColor: '#374151',
    TextColor: '#f9fafb',
    // Dark rows
    RowBg: '#1f2937',
    RowHoverColor: '#374151',
    RowBorderColor: '#4b5563',
    // Status styling
    StatusBgColor: '#059669',
    StatusTextColor: '#ffffff'
  }}
/>

Compact Mobile-Friendly Design

<TableComponent
  column={['Name', 'Status']}
  data={users}
  Layout={['name', 'status']}
  styles={{
    // Smaller text for mobile
    TitleText: 12,
    FontSize: 12,
    // Compact rows
    RowHeight: 35,
    // Subtle styling
    HeaderBg: '#f8fafc',
    RowHoverColor: '#f1f5f9',
    TableBorderColor: '#e2e8f0'
  }}
/>

High Contrast Accessibility Theme

<TableComponent
  column={['ID', 'Name', 'Status']}
  data={users}
  Layout={['id', 'name', 'status']}
  styles={{
    // High contrast colors
    TitleColor: '#000000',
    TextColor: '#000000',
    HeaderBg: '#ffffff',
    RowBg: '#ffffff',
    // Strong borders
    TableBorderColor: '#000000',
    HeaderBorderColor: '#000000',
    RowBorderColor: '#000000',
    // Hover effects
    RowHoverColor: '#f0f0f0',
    // Status with high contrast
    StatusBgColor: '#000000',
    StatusTextColor: '#ffffff'
  }}
/>

Corporate Brand Theme

<TableComponent
  column={['Employee', 'Department', 'Status']}
  data={employees}
  Layout={['name', 'department', 'status']}
  avatar={{
    column: 0,
    imgUrl: 'avatar',
    title: 'name'
  }}
  styles={{
    // Corporate blue theme
    HeaderBg: '#1e40af',
    TitleColor: '#ffffff',
    TitleFontStyle: 'bold',
    // Clean white table
    TableBg: '#ffffff',
    TextColor: '#1f2937',
    // Professional row styling
    RowHeight: 55,
    RowHoverColor: '#eff6ff',
    RowBg: '#ffffff',
    // Avatar styling
    AvatarSize: 45,
    AvatarBorderRadius: '8px',
    // Status badges
    StatusBgColor: '#1e40af',
    StatusTextColor: '#ffffff',
    // Action buttons
    ActionsButtonBg: '#1e40af',
    ActionsButtonColor: '#ffffff',
    ActionsButtonHoverBg: '#1d4ed8'
  }}
/>

Props Deep Dive

Understanding Each Prop

column and Layout - The Foundation

These two props work together to define your table structure:

// Define what users see
column={['ID', 'Name', 'Email', 'Role']}
// Define where data comes from
Layout={['id', 'name', 'email', 'role']}
// For nested data
Layout={['id', 'user.name', 'user.email', 'user.role']}

data - Your Data Source

const data = [
  { id: 1, name: 'John', email: '[email protected]' },
  { id: 2, name: 'Jane', email: '[email protected]' }
];
// Works with complex nested data too
const complexData = [
  {
    id: 1,
    user: { name: 'John', email: '[email protected]' },
    team: [
      { name: 'Alice', avatar: 'url1' },
      { name: 'Bob', avatar: 'url2' }
    ]
  }
];

avatar - Single User Display

Perfect for showing profile pictures:

avatar={{
  column: 1,           // Show avatar in 2nd column (0-based)
  imgUrl: 'avatar',    // Use 'avatar' property for image URL
  title: 'name',       // Show 'name' as tooltip
  subtitle: 'role'     // Show 'role' as subtitle below avatar
}}

multiAvatar - Team Display

Great for showing multiple users in one cell:

multiAvatar={{
  column: 3,           // Show in 4th column
  imgArray: 'team',    // Array of team member objects
  imgUrl: 'avatar',    // Avatar URL in each team member
  name: 'name'         // Name for tooltips
}}

actions - Row Operations

Add functionality to each row:

actions={{
  idkey: 'id',         // Default: 'id'
  view: '/users',      // Route for view action
  edit: '/users',      // Route for edit action
  delete: handleDelete, // Function called on delete
  onNavigate: (path) => navigate(path) // Handle navigation
}}

checkbox - Row Selection

Enable multi-select functionality:

// Controlled (external state)
const [selected, setSelected] = useState([]);
<TableComponent
  checkbox={{ selectedRows: selected, setSelectedRows: setSelected }}
  ...
/>

loading - Loading States

Show loading indicator:

{loading ? (
  <TableComponent loading={true} ... />
) : (
  <TableComponent data={data} ... />
)}

className - Custom CSS

Add your own styling:

<TableComponent className="my-custom-table responsive-table" ... />

styles - Complete Customization

See Complete Styling Guide above for full details.

Live Demo

👉 Try it now on CodeSandbox: https://codesandbox.io/p/sandbox/wizardly-mccarthy-4rrj6z

Connect With Me

You can reach out to me here:

• Email: [email protected]
• LinkedIn: Moniruzzaman Ripon
• GitHub: md-moniruzzaman01

License

MIT © Md Moniruzzaman

Made with ❤️ for the React community