KeyValueTable #

A modern, highly customizable Flutter table widget for clean, perfectly aligned key-value pairs. Designed to follow modern UI design standards (Material 3, Apple HIG, Stripe, Shopify Polaris) with automatic 2-column clean whitespace, optional separators, configurable key/value alignments, responsive stacked layouts, and granular item-level controls.

Desktop & Web Showcase #

Mobile Responsive Showcase #

Features #

• ✨ Modern Clean Whitespace by Default: No colons by default; renders a clean 2-column layout with consistent horizontalGap.
• 📐 Key & Value Alignment Customization: Align keys and values independently (e.g. left-aligned keys with right-aligned values for financial receipts, or right-aligned keys with colon gutters for inspector forms).
• 🏷️ Granular Per-Row Control (KeyValueItem): Define leading icons, trailing badges/actions, tooltips, and per-item styles or tap handlers.
• 📱 Responsive & Stacked Modes: Switch between horizontal, stacked (label on top, value below), or auto (switches automatically on mobile breakpoints).
• 📏 Density Presets: compact (2px), regular (6px), and comfortable (12px) padding presets.
• 📋 Tap-to-Copy (copyable): Built-in one-tap clipboard copying with a floating SnackBar or custom callback.
• ➖ Built-in Dividers & Row Styling: Easily enable subtle horizontal row dividers (showDividers) or alternating zebra striping.
• ❓ Null Handling: Automatic fallback placeholder (nullPlaceholder: '—') and optional empty row filtering (hideEmptyRows: true).
• 🔤 Text Selectable: Wrap entire table in SelectionArea with a single flag (isSelectable: true).
• 🧩 Rich Value Widgets: Pass any widget (Chip, Badge, ElevatedButton, custom status indicators) directly as a value.

Getting started #

Add key_value_table to your pubspec.yaml:

dependencies:
  key_value_table: ^0.1.0

Or run:

flutter pub add key_value_table

Usage Scenarios #

1. Modern Clean Key-Value (Default) #

By default, colons are omitted and keys and values are cleanly separated by whitespace:

import 'package:key_value_table/key_value_table.dart';

KeyValueTable(
  density: KeyValueDensity.comfortable,
  data: const {
    'Full Name': 'Dr. Alexander Fleming',
    'Specialty': 'Microbiology & Immunology',
    'Hospital': "St. Mary's Hospital, London",
    'Registered': 1928,
  },
)

2. Financial & E-Commerce Receipt (Right-Aligned Values) #

Align keys to the left and currency values to the right with horizontal row dividers:

KeyValueTable(
  keyAlignment: Alignment.centerLeft,
  valueAlignment: Alignment.centerRight,
  showDividers: true,
  data: {
    'Noise-Canceling Headphones': '$299.00',
    'Eco Protection Plan (2 Yr)': '$39.00',
    'Standard Shipping': 'FREE',
    'Estimated Tax': '$24.50',
    'Order Total': const Text(
      '$362.50 USD',
      style: TextStyle(fontWeight: FontWeight.bold, fontSize: 15),
    ),
  },
)

3. Inspector / Form Layout (Right-Aligned Keys with Colons) #

Create a classic inspector where all keys end at the same column and colons line up vertically:

KeyValueTable(
  separator: ':',
  separatorWidth: 20.0,
  keyAlignment: Alignment.centerRight,
  valueAlignment: Alignment.centerLeft,
  data: const {
    'Host': '10.244.3.188',
    'Environment': 'Production',
    'Port': 8080,
  },
)

4. Server Diagnostics (Zebra Striping & Tap-to-Copy) #

Enable copyable: true to let users tap any row to copy its value to the clipboard:

KeyValueTable(
  density: KeyValueDensity.compact,
  alternateRowColor: Colors.grey.shade100,
  copyable: true,
  data: {
    'Host': 'api.production.internal',
    'Cluster': 'k8s-us-east-1',
    'API Token': 'sk_live_99a8b7c6d5e4f3a2b1c0',
    'Backup Node': null, // Renders '—'
  },
)

5. Responsive & Stacked Layout (Mobile-Friendly) #

Stack keys and values vertically for small screens or multiline descriptions:

KeyValueTable(
  layout: KeyValueLayout.stacked, // or KeyValueLayout.auto with breakpoint: 480
  density: KeyValueDensity.comfortable,
  showDividers: true,
  data: const {
    'Architecture Goal':
        'Deliver deterministic, highly extensible key-value presentation across all Flutter form factors.',
    'Telemetry Endpoint':
        'https://telemetry.analytics.internal/v2/ingest?batch=true&compress=gzip',
  },
)

6. Granular Row Control with KeyValueItem #

Use KeyValueTable.items to configure icons, tooltips, and per-item styles:

KeyValueTable.items(
  density: KeyValueDensity.comfortable,
  showDividers: true,
  items: [
    const KeyValueItem(
      leading: Icon(Icons.person_outline, size: 18),
      key: 'Account Owner',
      value: 'Amrit (Senior Engineer)',
      tooltip: 'Verified organization primary contact',
    ),
    const KeyValueItem(
      leading: Icon(Icons.verified_user_outlined, size: 18, color: Colors.teal),
      key: 'Two-Factor Auth',
      value: 'Enforced via FIDO2',
      trailing: Icon(Icons.check_circle, size: 16, color: Colors.teal),
    ),
  ],
)

Properties Reference #

Running the Example Showcase App #

The repository includes a comprehensive, interactive showcase app under example/ demonstrating all 6 scenarios with real-time Light/Dark theme toggling and responsive grid layouts.

To run it locally:

# 1. Clone the repository
git clone https://github.com/Amrit1345/key_value_table.git

# 2. Navigate to the example project
cd key_value_table/example

# 3. Get dependencies and run
flutter pub get
flutter run

You can run it across Web, Desktop (macOS, Linux, Windows), and Mobile (Android, iOS):

flutter run -d chrome    # Run in Chrome
flutter run -d linux     # Run on Linux desktop
flutter run -d macos     # Run on macOS desktop
flutter run -d windows   # Run on Windows desktop

Contributing #

Contributions are always welcome! Whether you are fixing bugs, improving documentation, or proposing new layout modes:

1. Read our Contributing Guide to get started.
2. Review our Code of Conduct.
3. Check out the Issue Tracker to report bugs or request features.
4. Submit a Pull Request following our PR Template.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Additional Information #

• Package Repository: github.com/Amrit1345/key_value_table
• Example Showcase: github.com/Amrit1345/key_value_table/tree/main/example
• Issue Tracker: github.com/Amrit1345/key_value_table/issues