jsoncrack

A Flutter package that embeds the JsonCrack JSON viewer as a widget in your Flutter application.

JsonCrack provides an interactive, visual way to explore JSON data using a graph-based tree view with zoom, pan, collapsible nodes, and more.

Demo App — Try the interactive example online.

Features

  • Visual JSON tree viewer — renders JSON as an interactive graph with zoom and pan
  • Light and dark themes — automatically adapts to your app's theme
  • 5 configurable options — layout direction, grid, controls, auto-center, and node limit
  • Type-safe API — use JsonCrackLayoutDirection enum for compile-time safety
  • Ready-state callback — know when the viewer is fully loaded via onReady
  • Custom loading UI — provide a custom loading indicator with loadingBuilder
  • Cross-platform — works on web (iframe), mobile, and desktop (InAppWebView)
  • Responsive example app — the demo app adapts to mobile with a drawer, bottom sheet editor, and compact status bar
  • Easy to use — drop-in widget with minimal setup

Getting started

1. Add the dependency

Add jsoncrack to your pubspec.yaml:

dependencies:
  jsoncrack: ^0.2.0

Or install via the command line:

flutter pub add jsoncrack

2. Use the widget

No manual build or local web server is required! By default, the widget connects to the official hosted CDN (https://jsoncrack-bdf.pages.dev/cdn/):

import 'package:flutter/material.dart';
import 'package:jsoncrack/jsoncrack.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: JsonCrackView(
          json: '''
{
  "name": "Alice",
  "age": 25,
  "hobbies": ["reading", "coding", "hiking"]
}
          ''',
        ),
      ),
    );
  }
}

Usage

Basic usage

JsonCrackView(
  json: '{"key": "value"}',
)

With type-safe options

JsonCrackView(
  json: '{"key": "value"}',
  brightness: Brightness.dark,
  options: JsonCrackOptions(
    layoutDirection: JsonCrackLayoutDirection.down,
    showGrid: false,
  ),
)

With ready callback

JsonCrackView(
  json: '{"key": "value"}',
  onReady: () {
    print('Viewer is ready and displaying data');
  },
)

With custom loading UI

JsonCrackView(
  json: '{"key": "value"}',
  loadingBuilder: (context, progress) {
    return const Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          CircularProgressIndicator(),
          SizedBox(height: 16),
          Text('Loading JSON viewer...'),
        ],
      ),
    );
  },
)

Available options

Option Type Default Description
layoutDirection JsonCrackLayoutDirection / String right Tree layout direction (right, down, left, up)
showGrid bool true Show the background grid
showControls bool false Show built-in pan/zoom camera controls
centerOnLayout bool true Auto-center the view on layout changes
maxRenderableNodes int 1500 Maximum nodes to render before showing a fallback

Layout directions

JsonCrackLayoutDirection.right  // Tree grows to the right (default)
JsonCrackLayoutDirection.down   // Tree grows downward
JsonCrackLayoutDirection.left   // Tree grows to the left
JsonCrackLayoutDirection.up     // Tree grows upward

For backward compatibility, string values are also accepted:

JsonCrackOptions(layoutDirection: 'DOWN')

Customization examples

Show pan/zoom controls

Enable built-in camera controls for users who prefer button-based navigation:

JsonCrackView(
  json: myJson,
  options: JsonCrackOptions(
    showControls: true,
  ),
)

Limit renderable nodes

For large JSON payloads, cap the number of rendered nodes to maintain performance:

JsonCrackView(
  json: largeJson,
  options: JsonCrackOptions(
    maxRenderableNodes: 500,
  ),
)

Tip: For smooth interaction, keep maxRenderableNodes between 300–500. The default is 1500.

Hosting & Self-Embedding

By default, the package automatically loads the widget from the hosted Cloudflare CDN:

https://jsoncrack-bdf.pages.dev/cdn/

Because the widget is hosted on a high-availability CDN, no local web server or build step is needed in your Flutter projects.

Using your own self-hosted widget or CDN

If you prefer to self-host or embed your own copy (for air-gapped environments or custom branding):

  1. Build the jsoncrack-react app from source using ./build-json-crack.sh or make export, then copy the output directory to your web server, CDN, or hosting provider.

  2. Ensure your server headers allow cross-origin iframe embedding:

    Content-Security-Policy: frame-ancestors *
    Access-Control-Allow-Origin: *
    
  3. Pass your custom URL to JsonCrackView:

JsonCrackView(
  json: '{"key": "value"}',
  url: 'https://your-domain.com/cdn/',
)

Updating JSON dynamically

The widget automatically detects changes and updates the viewer:

JsonCrackView(
  json: _currentJson, // When this changes, the viewer updates
  options: _currentOptions,
)

Demo

A live demo app is available at jsoncrack-bdf.pages.dev. It showcases all customization options, theme switching, sample datasets, and responsive mobile support including:

  • Desktop: Full layout with sidebar, editor panel, and status bar
  • Tablet: Viewer-focused layout with compact controls
  • Mobile: Full-width viewer with drawer navigation, bottom sheet JSON editor, and floating action button

Architecture

The package uses a platform-specific implementation:

  • Web: An iframe loads the JsonCrack widget, communicating via postMessage.
  • Mobile/Desktop: WebViewWidget (via webview_all) renders the HTML and communicates via JavaScript evaluation.

The JsonCrackView widget automatically selects the correct implementation at compile time using Dart's conditional imports.

Example project

See the example/ directory for a complete Flutter app that demonstrates:

  • Theme switching (light/dark)
  • Layout direction toggling with type-safe enum
  • All 5 customization options
  • Dynamic JSON input with real-time validation
  • 6 preset sample JSON datasets
  • Node count display
  • Viewer ready-state notification
  • JSON formatting and reset
  • Responsive mobile support — narrow layout with drawer, bottom sheet editor, and compact status bar

To run the example:

make example-web

Requirements

  • Flutter SDK >= 1.17.0
  • Dart SDK >= 3.8.1
  • Node.js and npm (only needed if building jsoncrack-react from source)

Additional Documentation

License

See the LICENSE file for details.

© 2025 floriansabate.top

Libraries

jsoncrack
A Flutter package that embeds the JsonCrack JSON viewer as a widget in your Flutter application.