Json2UI - Flutter Package
Json2UI is a powerful, production-ready Flutter package that revolutionizes UI development by enabling you to create dynamic, responsive, and theme-aware user interfaces from JSON configurations. Built with performance, extensibility, and developer experience in mind, it provides a comprehensive solution for building complex Flutter applications with minimal code.
β¨ Key Features
π Dynamic Widget Creation
- JSON-to-Widget Conversion: Transform JSON configurations into fully functional Flutter widgets
- Type-Safe Processing: Built-in validation and type checking for all widget properties
- Nested Widget Support: Create complex widget trees with unlimited nesting depth
- Action Handling: Built-in support for user interactions and event handling
π¨ Advanced Responsive Design
- Mantine-Inspired Breakpoints: Professional breakpoint system (xs, sm, md, lg, xl, xl2)
- Responsive Value Resolution: Automatic value selection based on screen size
- Flexible Layout System: Support for responsive containers, grids, and flex layouts
- Device Orientation Support: Automatic adaptation to portrait and landscape modes
π§ Powerful Property Processing
- Async Property Validation: Real-time validation with custom error handling
- Property Transformation: Automatic type conversion and value transformation
- Default Value Injection: Intelligent default value management
- Middleware Support: Extensible processing pipeline with custom middleware
π― Extensible Custom Widgets
- Custom Widget Builders: Easy registration of custom widget implementations
- Property Processor Integration: Full integration with property processing system
- Inheritance Support: Build upon existing widgets with custom extensions
- Plugin Architecture: Modular design for easy extension and customization
π Comprehensive Theming
- Theme-Aware Rendering: Automatic theme application to all widgets
- Light/Dark Mode Support: Built-in support for system theme detection
- Custom Theme Configuration: Flexible theme customization with JsonTheme
- Component-Specific Theming: Individual theming for buttons, containers, and text
β‘ Performance & Animation
- Optimized Rendering: High-performance widget creation and rendering
- Smooth Animations: Built-in support for Lottie animations and transitions
- Memory Efficient: Minimal memory footprint with intelligent caching
- Benchmark Tested: Comprehensive performance benchmarks included
π± Cross-Platform Excellence
- Universal Compatibility: Works seamlessly on iOS, Android, Web, and Desktop
- Platform-Specific Features: Automatic adaptation to platform capabilities
- Web Optimization: Special optimizations for web deployment
- Desktop Support: Full support for Windows, macOS, and Linux
π§ͺ Enterprise-Grade Quality
- Comprehensive Testing: 326+ tests with >90% code coverage
- Production Ready: Battle-tested in production environments
- Type Safety: Full Dart type safety with compile-time checks
- Error Handling: Robust error handling with detailed error messages
π¦ Installation
Requirements
Before installing Json2UI, ensure you have the following:
- Flutter: >= 3.10.0
- Dart: >= 3.9.0
- Platform Support: iOS 11+, Android API 21+, Web, Windows, macOS, Linux
Add to Your Project
Add Json2UI to your pubspec.yaml file:
dependencies:
json2ui: ^1.0.0
# Optional: For Lottie animations
lottie: ^3.3.2
Install Dependencies
Run the following command to install the package:
flutter pub get
Platform-Specific Setup
iOS
No additional setup required. Json2UI works out of the box on iOS.
Android
No additional setup required. Json2UI works out of the box on Android.
Web
For web deployment, ensure you have the latest Flutter web support:
flutter config --enable-web
flutter create . --platforms web
Desktop (Windows/macOS/Linux)
For desktop support:
# Windows
flutter config --enable-windows-desktop
# macOS
flutter config --enable-macos-desktop
# Linux
flutter config --enable-linux-desktop
Import the Package
Add the import statement to your Dart files:
import 'package:json2ui/json2ui.dart';
Verify Installation
Create a simple test to verify the installation:
import 'package:flutter/material.dart';
import 'package:json2ui/json2ui.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
body: JsonWidgetFactory.fromData(
{
'type': 'text',
'properties': {
'data': 'Json2UI is working!',
'style': {'fontSize': 24.0, 'fontWeight': 'bold'}
}
},
context,
),
),
);
}
}
Troubleshooting
If you encounter issues:
- Ensure Flutter version compatibility: Run
flutter --versionto check your Flutter version - Clean and rebuild: Run
flutter clean && flutter pub get - Check platform setup: Ensure your target platform is properly configured
- Update dependencies: Run
flutter pub upgradeto get the latest versions
π Quick Start
Get started with Json2UI in just a few minutes! This guide will walk you through creating your first JSON-powered UI.
Step 1: Basic Widget Creation
Let's start with a simple example that creates a styled container with text:
import 'package:flutter/material.dart';
import 'package:json2ui/json2ui.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
// Define your UI as JSON
final jsonConfig = {
'type': 'container',
'properties': {
'color': '#E3F2FD',
'padding': 16.0,
'borderRadius': 8.0,
'child': {
'type': 'text',
'properties': {
'data': 'Hello from JSON!',
'style': {
'fontSize': 24.0,
'fontWeight': 'bold',
'color': '#1976D2',
},
},
},
},
};
return MaterialApp(
home: Scaffold(
appBar: AppBar(title: const Text('Json2UI Demo')),
body: JsonWidgetFactory.fromData(jsonConfig, context),
),
);
}
}
Step 2: Adding Interactivity
Now let's add a button with action handling:
class InteractiveExample extends StatefulWidget {
const InteractiveExample({super.key});
@override
State<InteractiveExample> createState() => _InteractiveExampleState();
}
class _InteractiveExampleState extends State<InteractiveExample> {
String _message = 'Click the button!';
@override
Widget build(BuildContext context) {
final jsonConfig = {
'type': 'column',
'properties': {
'children': [
{
'type': 'text',
'properties': {
'data': _message,
'style': {'fontSize': 18.0},
},
},
{
'type': 'elevated_button',
'properties': {
'child': {
'type': 'text',
'properties': {'data': 'Click Me!'},
},
'onPressed': {'action': 'button_clicked', 'data': 'Hello!'},
},
},
],
},
};
return Scaffold(
appBar: AppBar(title: const Text('Interactive Demo')),
body: JsonWidgetFactory.fromData(
jsonConfig,
context,
actionHandler: (action, data) {
if (action == 'button_clicked') {
setState(() {
_message = 'Button clicked with data: $data';
});
}
},
),
);
}
}
Step 3: Responsive Design
Create responsive layouts that adapt to different screen sizes:
class ResponsiveExample extends StatelessWidget {
const ResponsiveExample({super.key});
@override
Widget build(BuildContext context) {
final jsonConfig = {
'type': 'container',
'properties': {
'padding': 16.0,
'child': {
'type': 'column',
'properties': {
'children': [
{
'type': 'text',
'properties': {
'data': 'Responsive Layout',
'style': {'fontSize': 24.0, 'fontWeight': 'bold'},
},
},
{
'type': 'row',
'properties': {
'children': [
{
'type': 'container',
'properties': {
'color': '#FFF3E0',
'padding': 16.0,
'width': {'xs': '100%', 'sm': '50%', 'md': '33%'},
'height': 100.0,
'child': {
'type': 'text',
'properties': {'data': 'Column 1'},
},
},
},
{
'type': 'container',
'properties': {
'color': '#E8F5E8',
'padding': 16.0,
'width': {'xs': '100%', 'sm': '50%', 'md': '33%'},
'height': 100.0,
'child': {
'type': 'text',
'properties': {'data': 'Column 2'},
},
},
},
{
'type': 'container',
'properties': {
'color': '#F3E5F5',
'padding': 16.0,
'width': {'xs': '100%', 'sm': '50%', 'md': '33%'},
'height': 100.0,
'child': {
'type': 'text',
'properties': {'data': 'Column 3'},
},
},
},
],
},
},
],
},
},
},
};
return Scaffold(
appBar: AppBar(title: const Text('Responsive Demo')),
body: JsonWidgetFactory.fromData(jsonConfig, context),
);
}
}
Step 4: Custom Widget Registration
Create and register your own custom widgets:
import 'package:json2ui/json2ui.dart';
// 1. Create a custom widget builder
class CustomCardBuilder extends JsonWidgetBuilder {
final PropertyProcessor _processor = PropertyProcessor()
..addValidator('title', (value) => value is String && value.isNotEmpty)
..addTransformer('backgroundColor', PropertyTransformers.color)
..addDefault('elevation', 4.0);
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
return FutureBuilder<Map<String, dynamic>>(
future: _processor.processAsync(properties),
builder: (context, snapshot) {
if (snapshot.connectionState == ConnectionState.waiting) {
return const CircularProgressIndicator();
}
final processedProps = snapshot.data ?? properties;
return Card(
elevation: processedProps['elevation'] ?? 4.0,
color: processedProps['backgroundColor'],
child: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
processedProps['title'] ?? '',
style: Theme.of(context).textTheme.headlineSmall,
),
if (processedProps['subtitle'] != null) ...[
const SizedBox(height: 8),
Text(
processedProps['subtitle'],
style: Theme.of(context).textTheme.bodyMedium,
),
],
if (children != null && children.isNotEmpty) ...[
const SizedBox(height: 16),
...children,
],
],
),
),
);
},
);
}
}
// 2. Register the custom widget
void main() {
// Register your custom widget
JsonWidgetRegistry.register('custom_card', CustomCardBuilder());
runApp(const MyApp());
}
// 3. Use the custom widget in JSON
class CustomWidgetExample extends StatelessWidget {
const CustomWidgetExample({super.key});
@override
Widget build(BuildContext context) {
final jsonConfig = {
'type': 'custom_card',
'properties': {
'title': 'Custom Card Title',
'subtitle': 'This is a custom card built with Json2UI',
'backgroundColor': '#E3F2FD',
'elevation': 6.0,
},
};
return Scaffold(
appBar: AppBar(title: const Text('Custom Widget Demo')),
body: JsonWidgetFactory.fromData(jsonConfig, context),
);
}
}
Step 5: Advanced Features
Explore advanced features like theming and property processing:
class AdvancedExample extends StatelessWidget {
const AdvancedExample({super.key});
@override
Widget build(BuildContext context) {
// Define a custom theme
final theme = JsonTheme(
primaryColor: '#2196F3',
secondaryColor: '#FF9800',
backgroundColor: '#FFFFFF',
surfaceColor: '#F5F5F5',
borderRadius: 8.0,
defaultPadding: 16.0,
buttonTheme: ButtonThemeConfig(
backgroundColor: '#2196F3',
textColor: '#FFFFFF',
borderRadius: 8.0,
padding: 12.0,
),
);
final jsonConfig = {
'type': 'container',
'properties': {
'padding': 20.0,
'child': {
'type': 'column',
'properties': {
'children': [
{
'type': 'text',
'properties': {
'data': 'Advanced Json2UI Features',
'style': {'fontSize': 24.0, 'fontWeight': 'bold'},
},
},
{
'type': 'elevated_button',
'properties': {
'child': {
'type': 'text',
'properties': {'data': 'Themed Button'},
},
'onPressed': {'action': 'button_pressed'},
},
},
],
},
},
},
};
return Scaffold(
appBar: AppBar(title: const Text('Advanced Demo')),
body: JsonWidgetRenderer.renderFromJson(
jsonConfig,
context,
theme: theme,
actionHandler: (action, data) {
print('Action: $action, Data: $data');
},
),
);
}
}
Next Steps
Now that you have the basics, explore these advanced topics:
- π± Responsive Design: Learn about breakpoint systems and responsive values
- π¨ Theming: Create custom themes and theme-aware components
- π§ Property Processing: Advanced validation, transformation, and middleware
- π― Custom Widgets: Build complex custom components
- β‘ Performance: Optimization techniques and best practices
Check out the full documentation for detailed API references and examples.
π§ API Reference
JsonWidgetFactory
The main entry point for creating widgets from JSON configurations.
Methods
fromData(Map<String, dynamic> data, BuildContext context, {ActionHandler? actionHandler, JsonTheme? theme})
-
Parameters:
data: JSON configuration objectcontext: Flutter BuildContextactionHandler: Optional callback for handling widget actionstheme: Optional custom theme configuration
-
Returns:
Widget- The rendered Flutter widget -
Example:
final widget = JsonWidgetFactory.fromData(jsonConfig, context, actionHandler: (action, data) => print('Action: $action'));
fromJson(String jsonString, BuildContext context, {ActionHandler? actionHandler, JsonTheme? theme})
- Parameters:
jsonString: JSON string configurationcontext: Flutter BuildContextactionHandler: Optional callback for handling widget actionstheme: Optional custom theme configuration
- Returns:
Widget- The rendered Flutter widget
JsonWidgetRenderer
Advanced widget renderer with theming and performance optimizations.
Methods
renderFromJson(String jsonString, BuildContext context, {JsonTheme? theme, ActionHandler? actionHandler, bool enableCaching = true})
- Parameters:
jsonString: JSON string configurationcontext: Flutter BuildContexttheme: Optional custom themeactionHandler: Optional action handlerenableCaching: Enable widget caching for performance
- Returns:
Widget- Themed and optimized widget
createThemedApp(Map<String, dynamic> config, {String title = 'Json2UI App', ThemeMode themeMode = ThemeMode.system})
- Parameters:
config: App configuration with theme and routestitle: App titlethemeMode: Theme mode (light, dark, system)
- Returns:
Widget- Complete themed MaterialApp
PropertyProcessor
Handles property validation, transformation, and processing.
Constructor
final processor = PropertyProcessor();
Methods
addValidator(String property, PropertyValidator validator)
-
Adds a validation function for a property
-
Example:
processor.addValidator('width', (value) => value is num && value > 0);
addTransformer(String property, PropertyTransformer transformer)
-
Adds a transformation function for a property
-
Example:
processor.addTransformer('color', (value) => Color(int.parse(value)));
addAsyncTransformer(String property, AsyncPropertyTransformer transformer)
-
Adds an asynchronous transformation function
-
Example:
processor.addAsyncTransformer('data', (value) async { final result = await fetchData(value); return result; });
addDefault(String property, dynamic defaultValue)
-
Sets a default value for a property
-
Example:
processor.addDefault('padding', 16.0);
addMiddleware(PropertyMiddleware middleware)
-
Adds middleware to the processing pipeline
-
Example:
processor.addMiddleware((properties) { properties['timestamp'] = DateTime.now(); return properties; });
process(Map<String, dynamic> properties)
- Processes properties synchronously
- Returns:
Map<String, dynamic>- Processed properties
processAsync(Map<String, dynamic> properties)
- Processes properties asynchronously
- Returns:
Future<Map<String, dynamic>>- Processed properties
PropertyTransformers
Utility class with built-in property transformers.
Static Methods
color(dynamic value)
- Transforms color values (hex strings, named colors, integers)
- Returns:
Color?
dimension(dynamic value)
- Transforms dimension values (numbers, strings, infinity)
- Returns:
double?
edgeInsets(dynamic value)
- Transforms edge insets (single value, symmetric, specific, map)
- Returns:
EdgeInsets?
alignment(dynamic value)
- Transforms alignment values (strings, maps)
- Returns:
Alignment?
JsonWidgetRegistry
Manages custom widget registrations.
Methods
register(String type, JsonWidgetBuilder builder)
-
Registers a custom widget builder
-
Example:
JsonWidgetRegistry.register('custom_card', CustomCardBuilder());
unregister(String type)
- Unregisters a custom widget builder
getBuilder(String type)
- Gets a registered builder by type
- Returns:
JsonWidgetBuilder?
isRegistered(String type)
- Checks if a widget type is registered
- Returns:
bool
JsonWidgetBuilder
Base class for creating custom widget builders.
Abstract Methods
build(BuildContext context, Map<String, dynamic> properties, List<Widget>? children, ActionHandler? actionHandler)
- Builds the widget from JSON properties
- Returns:
Widget
Optional Methods
canBuild(String type)
- Checks if this builder can build the given type
- Returns:
bool(default:true)
ResponsiveLayoutManager
Manages responsive breakpoints and values.
Methods
getBreakpoint(BuildContext context)
- Gets the current breakpoint for the context
- Returns:
String(xs, sm, md, lg, xl, xl2)
resolveValue<T>(dynamic value, BuildContext context, {T? defaultValue})
- Resolves responsive values based on current breakpoint
- Returns:
T?
isBreakpoint(String breakpoint, BuildContext context)
- Checks if current breakpoint matches
- Returns:
bool
JsonTheme
Configuration class for theming.
Constructor
final theme = JsonTheme(
primaryColor: '#2196F3',
secondaryColor: '#FF9800',
backgroundColor: '#FFFFFF',
surfaceColor: '#F5F5F5',
borderRadius: 8.0,
defaultPadding: 16.0,
buttonTheme: ButtonThemeConfig(...),
containerTheme: ContainerThemeConfig(...),
textColors: TextThemeColors(...),
);
Properties
primaryColor: Primary theme colorsecondaryColor: Secondary theme colorbackgroundColor: Background colorsurfaceColor: Surface colorborderRadius: Default border radiusdefaultPadding: Default padding valuebuttonTheme: Button theming configurationcontainerTheme: Container theming configurationtextColors: Text color theming
ActionHandler
Type definition for action handling callbacks.
typedef ActionHandler = void Function(String action, dynamic data);
PropertyValidator
Type definition for property validation functions.
typedef PropertyValidator = bool Function(dynamic value);
PropertyTransformer
Type definition for property transformation functions.
typedef PropertyTransformer = dynamic Function(dynamic value);
AsyncPropertyTransformer
Type definition for asynchronous property transformation.
typedef AsyncPropertyTransformer = Future<dynamic> Function(dynamic value);
PropertyMiddleware
Type definition for property processing middleware.
typedef PropertyMiddleware = Map<String, dynamic> Function(Map<String, dynamic> properties);
Error Classes
PropertyValidationException
- Thrown when property validation fails
- Properties:
message,property,value
JsonWidgetException
- Thrown when widget creation fails
- Properties:
message,type,properties
Responsive Design
Json2UI provides a powerful responsive design system inspired by Mantine's breakpoint system. You can define different values for different screen sizes using breakpoint objects.
Breakpoints
Json2UI uses the following breakpoints (inspired by Mantine):
xs: Extra small screens (< 576px)sm: Small screens (β₯ 576px)md: Medium screens (β₯ 768px)lg: Large screens (β₯ 992px)xl: Extra large screens (β₯ 1200px)xl2: Extra extra large screens (β₯ 1400px)
Basic Usage
final responsiveConfig = {
'type': 'container',
'properties': {
'padding': {
'xs': 8.0,
'sm': 12.0,
'md': 16.0,
'lg': 20.0,
'xl': 24.0,
},
'child': {
'type': 'text',
'properties': {
'data': 'Responsive Text',
'style': {
'fontSize': {
'xs': 14.0,
'sm': 16.0,
'md': 18.0,
'lg': 20.0,
'xl': 22.0,
},
},
},
},
},
};
Responsive Layouts
Create responsive layouts that adapt to different screen sizes:
final responsiveLayout = {
'type': 'column',
'properties': {
'children': [
{
'type': 'text',
'properties': {
'data': 'Responsive Header',
'style': {
'fontSize': {'xs': 20.0, 'md': 28.0, 'lg': 32.0},
'fontWeight': 'bold',
},
},
},
{
'type': 'row',
'properties': {
'children': [
{
'type': 'container',
'properties': {
'width': {'xs': '100%', 'sm': '50%', 'md': '33.33%'},
'height': 100.0,
'color': '#E3F2FD',
'margin': {'xs': 4.0, 'sm': 8.0},
'child': {
'type': 'text',
'properties': {'data': 'Column 1'},
},
},
},
{
'type': 'container',
'properties': {
'width': {'xs': '100%', 'sm': '50%', 'md': '33.33%'},
'height': 100.0,
'color': '#F3E5F5',
'margin': {'xs': 4.0, 'sm': 8.0},
'child': {
'type': 'text',
'properties': {'data': 'Column 2'},
},
},
},
{
'type': 'container',
'properties': {
'width': {'xs': '100%', 'sm': '50%', 'md': '33.33%'},
'height': 100.0,
'color': '#E8F5E8',
'margin': {'xs': 4.0, 'sm': 8.0},
'child': {
'type': 'text',
'properties': {'data': 'Column 3'},
},
},
},
],
},
},
],
},
};
Responsive Images and Media
final responsiveImage = {
'type': 'container',
'properties': {
'width': {'xs': 200.0, 'sm': 300.0, 'md': 400.0},
'height': {'xs': 150.0, 'sm': 225.0, 'md': 300.0},
'child': {
'type': 'image',
'properties': {
'src': 'https://example.com/image.jpg',
'fit': 'cover',
},
},
},
};
Responsive Typography
final responsiveTypography = {
'type': 'column',
'properties': {
'children': [
{
'type': 'text',
'properties': {
'data': 'Headline',
'style': {
'fontSize': {'xs': 24.0, 'sm': 28.0, 'md': 32.0, 'lg': 36.0},
'fontWeight': 'bold',
'color': {'light': '#000000', 'dark': '#FFFFFF'},
},
},
},
{
'type': 'text',
'properties': {
'data': 'Subheadline',
'style': {
'fontSize': {'xs': 16.0, 'sm': 18.0, 'md': 20.0},
'color': {'light': '#666666', 'dark': '#CCCCCC'},
},
},
},
],
},
};
Advanced Responsive Patterns
Conditional Rendering
final conditionalLayout = {
'type': 'container',
'properties': {
'child': {
'type': 'responsive_builder',
'properties': {
'xs': {
'type': 'column',
'properties': {'children': [/* mobile layout */]},
},
'md': {
'type': 'row',
'properties': {'children': [/* desktop layout */]},
},
},
},
},
};
Responsive Navigation
final responsiveNav = {
'type': 'container',
'properties': {
'height': 60.0,
'padding': {'xs': 8.0, 'sm': 16.0},
'child': {
'type': 'row',
'properties': {
'mainAxisAlignment': 'spaceBetween',
'children': [
{
'type': 'text',
'properties': {
'data': 'Logo',
'style': {
'fontSize': {'xs': 18.0, 'sm': 24.0},
'fontWeight': 'bold',
},
},
},
{
'type': 'row',
'properties': {
'children': [
// Navigation items - hidden on mobile
{
'type': 'text',
'properties': {
'data': 'Home',
'style': {'display': {'xs': 'none', 'sm': 'block'}},
},
},
// Hamburger menu for mobile
{
'type': 'icon_button',
'properties': {
'icon': 'menu',
'display': {'xs': 'block', 'sm': 'none'},
},
},
],
},
},
],
},
},
},
};
Best Practices
- Use Relative Units: Prefer percentages and relative units over fixed pixels
- Mobile-First: Design for mobile first, then enhance for larger screens
- Consistent Breakpoints: Use the same breakpoint values throughout your app
- Test All Sizes: Test your layouts on all target screen sizes
- Performance: Avoid complex calculations in responsive values
Responsive Utilities
Json2UI provides several utility functions for responsive development:
// Get current breakpoint
final breakpoint = ResponsiveLayoutManager().getBreakpoint(context);
// Check if current screen matches breakpoint
final isMobile = ResponsiveLayoutManager().isBreakpoint('xs', context);
// Resolve responsive value
final padding = ResponsiveLayoutManager().resolveValue(
{'xs': 8.0, 'sm': 16.0, 'md': 24.0},
context,
defaultValue: 16.0,
);
Integration with PropertyProcessor
Combine responsive design with property processing:
class ResponsiveCardBuilder extends JsonWidgetBuilder {
final PropertyProcessor _processor = PropertyProcessor()
..addTransformer('width', (value) {
if (value is Map) {
return ResponsiveLayoutManager().resolveValue(value, context);
}
return value;
});
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
return FutureBuilder<Map<String, dynamic>>(
future: _processor.processAsync(properties),
builder: (context, snapshot) {
// Build responsive card
},
);
}
}
π JSON Schema
Basic Structure
{
"type": "widget_type",
"properties": {
"property_name": "property_value"
},
"children": [
{
"type": "child_widget_type",
"properties": {}
}
]
}
Built-in Widget Types
container: Basic container with stylingtext: Text widget with stylingelevated_button: Button with Mantine-style defaultscolumn: Vertical layoutrow: Horizontal layoutlottie: Lottie animation widget
Property Types
- Colors: Hex strings (
"#FF0000"), named colors ("red") - Dimensions: Numbers, strings (
"24"), responsive objects - EdgeInsets: Numbers, arrays (
[8, 16]), objects ({"top": 8, "left": 16}) - Text Styles: Objects with font properties
- Responsive Values: Objects with breakpoint keys
π¨ Responsive Breakpoints
Json2UI uses Mantine-inspired breakpoints:
xs: < 576px (Extra small devices)sm: β₯ 576px (Small devices/tablets)md: β₯ 768px (Medium devices/small laptops)lg: β₯ 992px (Large devices/desktops)xl: β₯ 1200px (Extra large devices)xl2: β₯ 1400px (Ultra large devices)
π§ Advanced Features
Property Processing
PropertyProcessor is a powerful system for validating, transforming, and processing widget properties. It provides a flexible pipeline that can handle complex property requirements with ease.
Basic Setup
import 'package:json2ui/json2ui.dart';
final processor = PropertyProcessor();
Validation
Add validation rules to ensure property values meet your requirements:
// Simple type validation
processor.addValidator('width', (value) => value is num && value > 0);
// Complex validation with custom logic
processor.addValidator('email', (value) {
if (value is! String) return false;
return RegExp(r'^[^@]+@[^@]+\.[^@]+$').hasMatch(value);
});
// Multiple validators for the same property
processor.addValidator('age', (value) => value is int);
processor.addValidator('age', (value) => value >= 0 && value <= 150);
Transformation
Transform property values from one format to another:
// Color transformation
processor.addTransformer('backgroundColor', PropertyTransformers.color);
// Dimension transformation
processor.addTransformer('padding', PropertyTransformers.dimension);
// Custom transformation
processor.addTransformer('userName', (value) {
if (value is String) {
return value.trim().toLowerCase();
}
return value;
});
// Date transformation
processor.addTransformer('createdAt', (value) {
if (value is String) {
return DateTime.parse(value);
}
return value;
});
Asynchronous Processing
Handle async operations like API calls or complex computations:
// Async data fetching
processor.addAsyncTransformer('userData', (value) async {
if (value is int) {
final user = await fetchUserById(value);
return user;
}
return value;
});
// Async validation (e.g., checking uniqueness)
processor.addAsyncTransformer('username', (value) async {
if (value is String) {
final isAvailable = await checkUsernameAvailability(value);
if (!isAvailable) {
throw PropertyValidationException('Username is already taken');
}
return value;
}
return value;
});
Default Values
Set default values for properties when they're not provided:
processor.addDefault('enabled', true);
processor.addDefault('padding', 16.0);
processor.addDefault('backgroundColor', '#FFFFFF');
processor.addDefault('borderRadius', 8.0);
processor.addDefault('theme', 'light');
Middleware
Add middleware to modify properties globally:
// Add timestamp to all processed properties
processor.addMiddleware((properties) {
properties['processedAt'] = DateTime.now().toIso8601String();
properties['version'] = '1.0.0';
return properties;
});
// Environment-specific middleware
processor.addMiddleware((properties) {
properties['environment'] = const String.fromEnvironment('ENV', defaultValue: 'development');
return properties;
});
// Logging middleware
processor.addMiddleware((properties) {
print('Processing properties: ${properties.keys.join(', ')}');
return properties;
});
Complete Example
class CustomFormBuilder extends JsonWidgetBuilder {
final PropertyProcessor _processor = PropertyProcessor()
// Validation
..addValidator('email', (value) {
if (value is! String) return false;
return RegExp(r'^[^@]+@[^@]+\.[^@]+$').hasMatch(value);
})
..addValidator('age', (value) => value is int && value >= 18 && value <= 120)
// Transformation
..addTransformer('email', (value) => value?.toString().trim().toLowerCase())
..addTransformer('backgroundColor', PropertyTransformers.color)
..addTransformer('padding', PropertyTransformers.dimension)
// Async processing
..addAsyncTransformer('profileImage', (value) async {
if (value is String && value.startsWith('http')) {
// Download and cache image
return await downloadAndCacheImage(value);
}
return value;
})
// Defaults
..addDefault('backgroundColor', '#F5F5F5')
..addDefault('padding', 16.0)
..addDefault('borderRadius', 8.0)
// Middleware
..addMiddleware((properties) {
properties['submittedAt'] = DateTime.now().toIso8601String();
properties['formVersion'] = '2.1.0';
return properties;
});
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
return FutureBuilder<Map<String, dynamic>>(
future: _processor.processAsync(properties),
builder: (context, snapshot) {
if (snapshot.connectionState == ConnectionState.waiting) {
return const CircularProgressIndicator();
}
if (snapshot.hasError) {
return Text('Error: ${snapshot.error}');
}
final processedProps = snapshot.data!;
return Container(
padding: EdgeInsets.all(processedProps['padding']),
decoration: BoxDecoration(
color: processedProps['backgroundColor'],
borderRadius: BorderRadius.circular(processedProps['borderRadius']),
),
child: Column(
children: [
Text('Email: ${processedProps['email']}'),
Text('Age: ${processedProps['age']}'),
if (processedProps['profileImage'] != null)
Image.network(processedProps['profileImage']),
Text('Submitted: ${processedProps['submittedAt']}'),
],
),
);
},
);
}
}
Built-in Transformers
Json2UI provides several built-in transformers for common use cases:
// Color transformations
PropertyTransformers.color('#FF0000'); // Hex string
PropertyTransformers.color('red'); // Named color
PropertyTransformers.color(0xFF0000FF); // Integer
PropertyTransformers.color(Colors.blue); // Color object
// Dimension transformations
PropertyTransformers.dimension(100); // Number
PropertyTransformers.dimension('200.5'); // String
PropertyTransformers.dimension('infinity'); // Special values
// EdgeInsets transformations
PropertyTransformers.edgeInsets(16.0); // All sides
PropertyTransformers.edgeInsets([8.0, 16.0]); // Vertical, horizontal
PropertyTransformers.edgeInsets([1.0, 2.0, 3.0, 4.0]); // Top, right, bottom, left
PropertyTransformers.edgeInsets({'top': 10.0, 'left': 5.0}); // Map
// Alignment transformations
PropertyTransformers.alignment('center'); // Named alignment
PropertyTransformers.alignment({'x': -1.0, 'y': 1.0}); // Coordinate alignment
PropertyTransformers.alignment(Alignment.topLeft); // Alignment object
Error Handling
PropertyProcessor provides comprehensive error handling:
try {
final result = await processor.processAsync({
'email': 'invalid-email', // Will fail validation
'age': 150, // Will fail validation
});
} on PropertyValidationException catch (e) {
print('Validation failed: ${e.message}');
print('Property: ${e.property}');
print('Invalid value: ${e.value}');
}
Performance Considerations
- Caching: PropertyProcessor automatically caches processed results
- Async Optimization: Async transformers run in parallel when possible
- Memory Management: Processed properties are efficiently managed
- Validation Short-circuit: Validation failures stop further processing
Property Processing Best Practices
- Validate Early: Add validators for all critical properties
- Use Appropriate Transformers: Choose the right transformer for your data type
- Handle Async Carefully: Be mindful of async operation performance
- Provide Sensible Defaults: Always set reasonable default values
- Use Middleware Sparingly: Middleware affects all properties - use judiciously
- Error Handling: Always handle validation exceptions appropriately
- Test Thoroughly: Test all validation and transformation scenarios
Integration with Custom Widgets
PropertyProcessor integrates seamlessly with custom widget builders:
class AdvancedCardBuilder extends JsonWidgetBuilder {
late final PropertyProcessor _processor;
AdvancedCardBuilder() {
_processor = PropertyProcessor()
..addValidator('title', (value) => value is String && value.isNotEmpty)
..addTransformer('backgroundColor', PropertyTransformers.color)
..addTransformer('padding', PropertyTransformers.dimension)
..addDefault('elevation', 4.0)
..addDefault('borderRadius', 8.0);
}
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
return FutureBuilder<Map<String, dynamic>>(
future: _processor.processAsync(properties),
builder: (context, snapshot) {
if (!snapshot.hasData) {
return const CircularProgressIndicator();
}
final props = snapshot.data!;
return Card(
elevation: props['elevation'],
color: props['backgroundColor'],
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(props['borderRadius']),
),
child: Padding(
padding: EdgeInsets.all(props['padding']),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
props['title'],
style: Theme.of(context).textTheme.headlineSmall,
),
if (props['subtitle'] != null) ...[
const SizedBox(height: 8),
Text(props['subtitle']),
],
if (children != null) ...children,
],
),
),
);
},
);
}
}
Action Handling
final configWithActions = {
'type': 'elevated_button',
'properties': {
'text': 'Click Me',
'action': 'navigate_to_profile',
'actionData': {'userId': 123},
},
};
JsonWidgetFactory.fromData(
configWithActions,
context,
actionHandler: (action, data) async {
if (action == 'navigate_to_profile') {
// Handle navigation
Navigator.pushNamed(context, '/profile', arguments: data);
}
},
);
Theming Integration
// Automatic theme integration
final themedConfig = {
'type': 'text',
'properties': {
'text': 'Themed Text',
'style': {
'color': 'primary', // Uses theme primary color
'fontSize': 16.0,
},
},
};
π― Custom Widgets Guide
Json2UI's extensibility is powered by its custom widget system. You can create complex, reusable components that integrate seamlessly with the JSON-to-widget pipeline.
Creating a Custom Widget Builder
Every custom widget starts with a class that extends JsonWidgetBuilder:
import 'package:flutter/material.dart';
import 'package:json2ui/json2ui.dart';
class ProductCardBuilder extends JsonWidgetBuilder {
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
// Extract properties with defaults
final title = properties['title'] as String? ?? 'Product';
final price = properties['price'] as num? ?? 0.0;
final imageUrl = properties['imageUrl'] as String?;
final isOnSale = properties['isOnSale'] as bool? ?? false;
return Card(
elevation: 4.0,
margin: const EdgeInsets.all(8.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
if (imageUrl != null)
Image.network(
imageUrl,
height: 150,
width: double.infinity,
fit: BoxFit.cover,
),
Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
title,
style: Theme.of(context).textTheme.headlineSmall,
),
const SizedBox(height: 8),
Row(
children: [
Text(
'\$${price.toStringAsFixed(2)}',
style: TextStyle(
fontSize: 18,
fontWeight: FontWeight.bold,
color: isOnSale ? Colors.red : Colors.green,
),
),
if (isOnSale) ...[
const SizedBox(width: 8),
Container(
padding: const EdgeInsets.symmetric(
horizontal: 8,
vertical: 4,
),
decoration: BoxDecoration(
color: Colors.red,
borderRadius: BorderRadius.circular(12),
),
child: const Text(
'SALE',
style: TextStyle(
color: Colors.white,
fontSize: 12,
fontWeight: FontWeight.bold,
),
),
),
],
],
),
if (children != null && children.isNotEmpty) ...[
const SizedBox(height: 16),
...children,
],
],
),
),
],
),
);
}
}
Advanced Custom Widget with PropertyProcessor
For more complex widgets, integrate PropertyProcessor for validation and transformation:
class AdvancedProductCardBuilder extends JsonWidgetBuilder {
final PropertyProcessor _processor = PropertyProcessor()
// Validation
..addValidator('title', (value) => value is String && value.isNotEmpty)
..addValidator('price', (value) => value is num && value >= 0)
..addValidator('imageUrl', (value) {
if (value == null) return true; // Optional
return value is String && Uri.tryParse(value)?.isAbsolute == true;
})
// Transformation
..addTransformer('price', (value) {
if (value is num) return value.toDouble();
if (value is String) return double.tryParse(value) ?? 0.0;
return 0.0;
})
..addTransformer('backgroundColor', PropertyTransformers.color)
..addTransformer('borderRadius', PropertyTransformers.dimension)
// Async processing (e.g., image validation)
..addAsyncTransformer('imageUrl', (value) async {
if (value is String && value.isNotEmpty) {
// Validate image exists
final response = await http.head(Uri.parse(value));
if (response.statusCode != 200) {
throw PropertyValidationException('Image not accessible', property: 'imageUrl');
}
}
return value;
})
// Defaults
..addDefault('backgroundColor', Colors.white)
..addDefault('borderRadius', 8.0)
..addDefault('elevation', 4.0)
// Middleware
..addMiddleware((properties) {
properties['renderedAt'] = DateTime.now().toIso8601String();
return properties;
});
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
return FutureBuilder<Map<String, dynamic>>(
future: _processor.processAsync(properties),
builder: (context, snapshot) {
if (snapshot.connectionState == ConnectionState.waiting) {
return const Card(
child: SizedBox(
height: 200,
child: Center(child: CircularProgressIndicator()),
),
);
}
if (snapshot.hasError) {
return Card(
color: Colors.red.shade50,
child: Padding(
padding: const EdgeInsets.all(16.0),
child: Text(
'Error loading product: ${snapshot.error}',
style: const TextStyle(color: Colors.red),
),
),
);
}
final processedProps = snapshot.data!;
return Card(
elevation: processedProps['elevation'],
color: processedProps['backgroundColor'],
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(processedProps['borderRadius']),
),
margin: const EdgeInsets.all(8.0),
child: InkWell(
onTap: () {
actionHandler?.call('product_tapped', {
'productId': processedProps['id'],
'title': processedProps['title'],
});
},
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
if (processedProps['imageUrl'] != null)
ClipRRect(
borderRadius: BorderRadius.vertical(
top: Radius.circular(processedProps['borderRadius']),
),
child: Image.network(
processedProps['imageUrl'],
height: 150,
width: double.infinity,
fit: BoxFit.cover,
errorBuilder: (context, error, stackTrace) {
return Container(
height: 150,
color: Colors.grey.shade200,
child: const Icon(Icons.image_not_supported, size: 48),
);
},
),
),
Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
processedProps['title'],
style: Theme.of(context).textTheme.headlineSmall,
),
if (processedProps['subtitle'] != null) ...[
const SizedBox(height: 4),
Text(
processedProps['subtitle'],
style: Theme.of(context).textTheme.bodyMedium?.copyWith(
color: Colors.grey.shade600,
),
),
],
const SizedBox(height: 8),
Row(
children: [
Text(
'\$${processedProps['price'].toStringAsFixed(2)}',
style: TextStyle(
fontSize: 18,
fontWeight: FontWeight.bold,
color: processedProps['isOnSale'] == true
? Colors.red
: Colors.green,
),
),
if (processedProps['isOnSale'] == true) ...[
const SizedBox(width: 8),
Container(
padding: const EdgeInsets.symmetric(
horizontal: 8,
vertical: 4,
),
decoration: BoxDecoration(
color: Colors.red,
borderRadius: BorderRadius.circular(12),
),
child: const Text(
'SALE',
style: TextStyle(
color: Colors.white,
fontSize: 12,
fontWeight: FontWeight.bold,
),
),
),
],
],
),
if (processedProps['rating'] != null) ...[
const SizedBox(height: 8),
Row(
children: [
const Icon(Icons.star, color: Colors.amber, size: 16),
const SizedBox(width: 4),
Text(
processedProps['rating'].toString(),
style: Theme.of(context).textTheme.bodySmall,
),
],
),
],
if (children != null && children.isNotEmpty) ...[
const SizedBox(height: 16),
...children,
],
],
),
),
],
),
),
);
},
);
}
}
Registering Custom Widgets
Register your custom widgets with the JsonWidgetRegistry:
void main() {
// Register multiple custom widgets
JsonWidgetRegistry.register('product_card', ProductCardBuilder());
JsonWidgetRegistry.register('advanced_product_card', AdvancedProductCardBuilder());
JsonWidgetRegistry.register('custom_button', CustomButtonBuilder());
JsonWidgetRegistry.register('data_table', DataTableBuilder());
runApp(const MyApp());
}
Using Custom Widgets in JSON
Once registered, use your custom widgets in JSON configurations:
final productListConfig = {
'type': 'column',
'properties': {
'children': [
{
'type': 'advanced_product_card',
'properties': {
'id': 'product-1',
'title': 'Wireless Headphones',
'subtitle': 'Premium noise-cancelling wireless headphones',
'price': 299.99,
'imageUrl': 'https://example.com/headphones.jpg',
'isOnSale': true,
'rating': 4.5,
'backgroundColor': '#F8F9FA',
'borderRadius': 12.0,
'elevation': 6.0,
},
},
{
'type': 'advanced_product_card',
'properties': {
'id': 'product-2',
'title': 'Smart Watch',
'subtitle': 'Fitness tracking and health monitoring',
'price': 399.99,
'imageUrl': 'https://example.com/smartwatch.jpg',
'rating': 4.8,
'backgroundColor': '#FFFFFF',
'borderRadius': 16.0,
},
},
],
},
};
Complex Custom Widgets with State
For widgets that need internal state management:
class InteractiveChartBuilder extends JsonWidgetBuilder {
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
return _InteractiveChart(
data: properties['data'] as List<dynamic>? ?? [],
title: properties['title'] as String? ?? 'Chart',
type: properties['type'] as String? ?? 'bar',
actionHandler: actionHandler,
);
}
}
class _InteractiveChart extends StatefulWidget {
final List<dynamic> data;
final String title;
final String type;
final ActionHandler? actionHandler;
const _InteractiveChart({
required this.data,
required this.title,
required this.type,
this.actionHandler,
});
@override
State<_InteractiveChart> createState() => _InteractiveChartState();
}
class _InteractiveChartState extends State<_InteractiveChart> {
int _selectedIndex = -1;
@override
Widget build(BuildContext context) {
return Card(
child: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
widget.title,
style: Theme.of(context).textTheme.headlineSmall,
),
const SizedBox(height: 16),
SizedBox(
height: 200,
child: ListView.builder(
scrollDirection: Axis.horizontal,
itemCount: widget.data.length,
itemBuilder: (context, index) {
final item = widget.data[index];
final isSelected = index == _selectedIndex;
return GestureDetector(
onTap: () {
setState(() => _selectedIndex = index);
widget.actionHandler?.call('chart_item_selected', {
'index': index,
'data': item,
});
},
child: Container(
width: 60,
margin: const EdgeInsets.symmetric(horizontal: 4),
decoration: BoxDecoration(
color: isSelected ? Colors.blue : Colors.grey.shade300,
borderRadius: BorderRadius.circular(4),
),
child: Center(
child: Text(
item.toString(),
style: TextStyle(
color: isSelected ? Colors.white : Colors.black,
fontWeight: isSelected ? FontWeight.bold : FontWeight.normal,
),
),
),
),
);
},
),
),
],
),
),
);
}
}
Custom Widget with Animation
Create animated custom widgets:
class AnimatedCardBuilder extends JsonWidgetBuilder {
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
return _AnimatedCard(
title: properties['title'] as String? ?? 'Card',
content: properties['content'] as String? ?? '',
delay: properties['delay'] as int? ?? 0,
duration: properties['duration'] as int? ?? 500,
children: children,
);
}
}
class _AnimatedCard extends StatefulWidget {
final String title;
final String content;
final int delay;
final int duration;
final List<Widget>? children;
const _AnimatedCard({
required this.title,
required this.content,
required this.delay,
required this.duration,
this.children,
});
@override
State<_AnimatedCard> createState() => _AnimatedCardState();
}
class _AnimatedCardState extends State<_AnimatedCard>
with SingleTickerProviderStateMixin {
late AnimationController _controller;
late Animation<double> _animation;
@override
void initState() {
super.initState();
_controller = AnimationController(
duration: Duration(milliseconds: widget.duration),
vsync: this,
);
_animation = Tween<double>(
begin: 0.0,
end: 1.0,
).animate(CurvedAnimation(
parent: _controller,
curve: Curves.easeOut,
));
Future.delayed(Duration(milliseconds: widget.delay), () {
if (mounted) _controller.forward();
});
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return AnimatedBuilder(
animation: _animation,
builder: (context, child) {
return Transform.translate(
offset: Offset(0, 50 * (1 - _animation.value)),
child: Opacity(
opacity: _animation.value,
child: Card(
elevation: 4 * _animation.value,
child: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
widget.title,
style: Theme.of(context).textTheme.headlineSmall,
),
const SizedBox(height: 8),
Text(widget.content),
if (widget.children != null) ...[
const SizedBox(height: 16),
...widget.children!,
],
],
),
),
),
),
);
},
);
}
}
Best Practices for Custom Widgets
- Property Validation: Always validate input properties
- Error Handling: Provide meaningful error messages and fallbacks
- Performance: Use efficient rendering and avoid unnecessary rebuilds
- Accessibility: Support screen readers and keyboard navigation
- Theming: Respect the app's theme and provide theme customization
- Documentation: Document all properties and usage examples
- Testing: Write comprehensive tests for your custom widgets
- Reusability: Design widgets to be reusable across different contexts
Widget Registry Management
Manage your custom widgets effectively:
// Check if a widget is registered
bool isRegistered = JsonWidgetRegistry.isRegistered('my_widget');
// Get a registered builder
JsonWidgetBuilder? builder = JsonWidgetRegistry.getBuilder('my_widget');
// Unregister a widget
JsonWidgetRegistry.unregister('my_widget');
// List all registered widgets (for debugging)
void printRegisteredWidgets() {
// Note: This would require extending JsonWidgetRegistry
// with a method to list registered types
}
Advanced Patterns
Factory Pattern for Complex Widgets
abstract class WidgetFactory {
JsonWidgetBuilder createBuilder();
}
class MaterialWidgetFactory implements WidgetFactory {
@override
JsonWidgetBuilder createBuilder() {
return MaterialCardBuilder();
}
}
class CupertinoWidgetFactory implements WidgetFactory {
@override
JsonWidgetBuilder createBuilder() {
return CupertinoCardBuilder();
}
}
Dependency Injection
class InjectableWidgetBuilder extends JsonWidgetBuilder {
final ApiService apiService;
final CacheService cacheService;
InjectableWidgetBuilder({
required this.apiService,
required this.cacheService,
});
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
// Use injected services
return FutureBuilder(
future: apiService.fetchData(properties['endpoint']),
builder: (context, snapshot) {
// Build widget using services
},
);
}
}
This comprehensive guide shows how to create powerful, reusable custom widgets that integrate seamlessly with Json2UI's ecosystem.
π Theming Guide
Json2UI provides a comprehensive theming system that allows you to create beautiful, consistent, and adaptive user interfaces. The theming system integrates seamlessly with Flutter's built-in theming while providing additional customization options.
JsonTheme Configuration
The JsonTheme class is the core of Json2UI's theming system:
import 'package:flutter/material.dart';
import 'package:json2ui/json2ui.dart';
final jsonTheme = JsonTheme(
// Base theme configuration
brightness: Brightness.light,
primaryColor: Colors.blue,
secondaryColor: Colors.teal,
// Typography
fontFamily: 'Roboto',
headline1: TextStyle(
fontSize: 32,
fontWeight: FontWeight.bold,
color: Colors.black87,
),
headline2: TextStyle(
fontSize: 28,
fontWeight: FontWeight.w600,
color: Colors.black87,
),
bodyText1: TextStyle(
fontSize: 16,
color: Colors.black87,
),
// Component-specific themes
buttonTheme: JsonButtonTheme(
defaultColor: Colors.blue,
hoverColor: Colors.blue.shade700,
pressedColor: Colors.blue.shade800,
borderRadius: 8.0,
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
),
cardTheme: JsonCardTheme(
backgroundColor: Colors.white,
shadowColor: Colors.black12,
elevation: 4.0,
borderRadius: 12.0,
padding: const EdgeInsets.all(16),
),
inputTheme: JsonInputTheme(
backgroundColor: Colors.grey.shade50,
borderColor: Colors.grey.shade300,
focusColor: Colors.blue,
errorColor: Colors.red,
borderRadius: 8.0,
padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 16),
),
// Spacing and layout
spacing: JsonSpacing(
xs: 4.0,
sm: 8.0,
md: 16.0,
lg: 24.0,
xl: 32.0,
xxl: 48.0,
),
// Breakpoints for responsive design
breakpoints: JsonBreakpoints(
xs: 576,
sm: 768,
md: 992,
lg: 1200,
xl: 1400,
xl2: 1600,
),
// Custom theme extensions
extensions: {
'successColor': Colors.green,
'warningColor': Colors.orange,
'dangerColor': Colors.red,
'infoColor': Colors.blue,
},
);
Applying Themes
Apply your theme to the JsonWidgetFactory:
void main() {
// Create and configure your theme
final theme = JsonTheme(
brightness: Brightness.light,
primaryColor: Colors.indigo,
secondaryColor: Colors.pink,
// ... other configurations
);
// Apply theme to JsonWidgetFactory
JsonWidgetFactory.setTheme(theme);
runApp(const MyApp());
}
Light and Dark Mode Support
Json2UI automatically supports light and dark mode switching:
class MyApp extends StatefulWidget {
const MyApp({super.key});
@override
State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
ThemeMode _themeMode = ThemeMode.system;
void _toggleTheme() {
setState(() {
_themeMode = _themeMode == ThemeMode.light
? ThemeMode.dark
: ThemeMode.light;
});
}
@override
Widget build(BuildContext context) {
// Create light theme
final lightTheme = JsonTheme(
brightness: Brightness.light,
primaryColor: Colors.blue,
backgroundColor: Colors.white,
surfaceColor: Colors.grey.shade50,
// ... light theme configurations
);
// Create dark theme
final darkTheme = JsonTheme(
brightness: Brightness.dark,
primaryColor: Colors.blue.shade300,
backgroundColor: Colors.grey.shade900,
surfaceColor: Colors.grey.shade800,
// ... dark theme configurations
);
return MaterialApp(
theme: lightTheme.toMaterialThemeData(),
darkTheme: darkTheme.toMaterialThemeData(),
themeMode: _themeMode,
home: Scaffold(
appBar: AppBar(
title: const Text('Json2UI Theming'),
actions: [
IconButton(
icon: Icon(_themeMode == ThemeMode.light
? Icons.dark_mode
: Icons.light_mode),
onPressed: _toggleTheme,
),
],
),
body: JsonWidgetFactory.buildFromJson(
context,
// Your JSON configuration will automatically use the current theme
yourJsonConfig,
),
),
);
}
}
Dynamic Theme Switching
Create themes that can be switched at runtime:
class ThemeProvider extends ChangeNotifier {
JsonTheme _currentTheme = lightTheme;
JsonTheme get currentTheme => _currentTheme;
void setTheme(JsonTheme theme) {
_currentTheme = theme;
JsonWidgetFactory.setTheme(theme);
notifyListeners();
}
void toggleTheme() {
if (_currentTheme.brightness == Brightness.light) {
setTheme(darkTheme);
} else {
setTheme(lightTheme);
}
}
}
// Usage in widgets
class ThemedWidget extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Consumer<ThemeProvider>(
builder: (context, themeProvider, child) {
return JsonWidgetFactory.buildFromJson(
context,
{
'type': 'container',
'properties': {
'color': themeProvider.currentTheme.primaryColor,
'child': {
'type': 'text',
'properties': {
'data': 'Themed Content',
'style': {
'color': themeProvider.currentTheme.onPrimaryColor,
},
},
},
},
},
);
},
);
}
}
Component-Specific Theming
Customize individual components with specific themes:
final customButtonTheme = JsonButtonTheme(
defaultColor: Colors.purple,
hoverColor: Colors.purple.shade700,
pressedColor: Colors.purple.shade800,
borderRadius: 25.0,
padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 14),
textStyle: const TextStyle(
fontSize: 16,
fontWeight: FontWeight.w600,
),
);
final customCardTheme = JsonCardTheme(
backgroundColor: Colors.white,
shadowColor: Colors.black.withOpacity(0.1),
elevation: 8.0,
borderRadius: 16.0,
padding: const EdgeInsets.all(20),
margin: const EdgeInsets.all(8),
);
final theme = JsonTheme(
buttonTheme: customButtonTheme,
cardTheme: customCardTheme,
// ... other configurations
);
Using Themes in JSON Configurations
Apply theme values directly in your JSON:
final themedConfig = {
'type': 'column',
'properties': {
'children': [
{
'type': 'card',
'properties': {
'color': '\${theme.primaryColor}',
'elevation': '\${theme.cardTheme.elevation}',
'borderRadius': '\${theme.cardTheme.borderRadius}',
'padding': '\${theme.cardTheme.padding}',
'child': {
'type': 'column',
'properties': {
'children': [
{
'type': 'text',
'properties': {
'data': 'Themed Card',
'style': {
'color': '\${theme.onPrimaryColor}',
'fontSize': '\${theme.headline2.fontSize}',
'fontWeight': '\${theme.headline2.fontWeight}',
},
},
},
{
'type': 'sized_box',
'properties': {
'height': '\${theme.spacing.md}',
},
},
{
'type': 'elevated_button',
'properties': {
'child': {
'type': 'text',
'properties': {
'data': 'Themed Button',
},
},
'style': {
'backgroundColor': '\${theme.buttonTheme.defaultColor}',
'foregroundColor': '\${theme.onPrimaryColor}',
'padding': '\${theme.buttonTheme.padding}',
'shape': {
'borderRadius': '\${theme.buttonTheme.borderRadius}',
},
},
},
},
],
},
},
},
},
],
},
};
Advanced Theme Customization
Create complex theme hierarchies and overrides:
class AdvancedTheme extends JsonTheme {
final Color accentColor;
final Color successColor;
final Color warningColor;
final Color errorColor;
const AdvancedTheme({
required this.accentColor,
required this.successColor,
required this.warningColor,
required this.errorColor,
// ... other parameters
}) : super(
primaryColor: accentColor,
// ... other configurations
);
// Custom theme methods
Color getStatusColor(String status) {
switch (status) {
case 'success':
return successColor;
case 'warning':
return warningColor;
case 'error':
return errorColor;
default:
return primaryColor;
}
}
// Override theme application
@override
ThemeData toMaterialThemeData() {
final baseTheme = super.toMaterialThemeData();
return baseTheme.copyWith(
// Custom theme extensions
extensions: [
...?baseTheme.extensions,
_CustomThemeExtension(
accentColor: accentColor,
successColor: successColor,
warningColor: warningColor,
errorColor: errorColor,
),
],
);
}
}
class _CustomThemeExtension extends ThemeExtension<_CustomThemeExtension> {
final Color accentColor;
final Color successColor;
final Color warningColor;
final Color errorColor;
const _CustomThemeExtension({
required this.accentColor,
required this.successColor,
required this.warningColor,
required this.errorColor,
});
@override
ThemeExtension<_CustomThemeExtension> copyWith({
Color? accentColor,
Color? successColor,
Color? warningColor,
Color? errorColor,
}) {
return _CustomThemeExtension(
accentColor: accentColor ?? this.accentColor,
successColor: successColor ?? this.successColor,
warningColor: warningColor ?? this.warningColor,
errorColor: errorColor ?? this.errorColor,
);
}
@override
ThemeExtension<_CustomThemeExtension> lerp(
ThemeExtension<_CustomThemeExtension>? other,
double t,
) {
if (other is! _CustomThemeExtension) return this;
return _CustomThemeExtension(
accentColor: Color.lerp(accentColor, other.accentColor, t)!,
successColor: Color.lerp(successColor, other.successColor, t)!,
warningColor: Color.lerp(warningColor, other.warningColor, t)!,
errorColor: Color.lerp(errorColor, other.errorColor, t)!,
);
}
}
Theme Inheritance and Overrides
Create theme variants that inherit from base themes:
// Base theme
final baseTheme = JsonTheme(
primaryColor: Colors.blue,
fontFamily: 'Roboto',
// ... base configurations
);
// High contrast variant
final highContrastTheme = baseTheme.copyWith(
primaryColor: Colors.blue.shade900,
backgroundColor: Colors.white,
surfaceColor: Colors.grey.shade100,
// Enhanced contrast colors
);
// Minimal variant
final minimalTheme = baseTheme.copyWith(
backgroundColor: Colors.grey.shade50,
surfaceColor: Colors.white,
cardTheme: baseTheme.cardTheme?.copyWith(
elevation: 0.0,
shadowColor: Colors.transparent,
),
// Reduced visual elements
);
Responsive Theming
Create themes that adapt to different screen sizes:
JsonTheme getResponsiveTheme(BuildContext context) {
final screenWidth = MediaQuery.of(context).size.width;
if (screenWidth < 600) {
// Mobile theme
return JsonTheme(
spacing: JsonSpacing(
xs: 2.0,
sm: 4.0,
md: 8.0,
lg: 12.0,
xl: 16.0,
xxl: 20.0,
),
cardTheme: JsonCardTheme(
padding: const EdgeInsets.all(12),
borderRadius: 8.0,
),
// ... mobile-specific configurations
);
} else if (screenWidth < 1200) {
// Tablet theme
return JsonTheme(
spacing: JsonSpacing(
xs: 4.0,
sm: 8.0,
md: 16.0,
lg: 24.0,
xl: 32.0,
xxl: 40.0,
),
cardTheme: JsonCardTheme(
padding: const EdgeInsets.all(16),
borderRadius: 12.0,
),
// ... tablet-specific configurations
);
} else {
// Desktop theme
return JsonTheme(
spacing: JsonSpacing(
xs: 6.0,
sm: 12.0,
md: 24.0,
lg: 36.0,
xl: 48.0,
xxl: 60.0,
),
cardTheme: JsonCardTheme(
padding: const EdgeInsets.all(24),
borderRadius: 16.0,
),
// ... desktop-specific configurations
);
}
}
Theme Persistence
Save and restore themes using shared preferences:
class ThemeManager {
static const String _themeKey = 'selected_theme';
static Future<void> saveTheme(String themeName) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString(_themeKey, themeName);
}
static Future<String?> loadTheme() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getString(_themeKey);
}
static JsonTheme getThemeByName(String name) {
switch (name) {
case 'light':
return lightTheme;
case 'dark':
return darkTheme;
case 'high_contrast':
return highContrastTheme;
default:
return lightTheme;
}
}
}
// Usage
class App extends StatefulWidget {
@override
State<App> createState() => _AppState();
}
class _AppState extends State<App> {
JsonTheme _currentTheme = lightTheme;
@override
void initState() {
super.initState();
_loadSavedTheme();
}
Future<void> _loadSavedTheme() async {
final themeName = await ThemeManager.loadTheme();
if (themeName != null) {
setState(() {
_currentTheme = ThemeManager.getThemeByName(themeName);
});
JsonWidgetFactory.setTheme(_currentTheme);
}
}
Future<void> _changeTheme(String themeName) async {
final newTheme = ThemeManager.getThemeByName(themeName);
setState(() {
_currentTheme = newTheme;
});
JsonWidgetFactory.setTheme(newTheme);
await ThemeManager.saveTheme(themeName);
}
@override
Widget build(BuildContext context) {
return MaterialApp(
theme: _currentTheme.toMaterialThemeData(),
home: Scaffold(
appBar: AppBar(
title: const Text('Themed App'),
actions: [
PopupMenuButton<String>(
onSelected: _changeTheme,
itemBuilder: (context) => [
const PopupMenuItem(
value: 'light',
child: Text('Light Theme'),
),
const PopupMenuItem(
value: 'dark',
child: Text('Dark Theme'),
),
const PopupMenuItem(
value: 'high_contrast',
child: Text('High Contrast'),
),
],
),
],
),
body: const Center(
child: Text('Theme persists across app restarts!'),
),
),
);
}
}
Best Practices for Theming
- Consistent Color Palette: Define a cohesive color scheme
- Semantic Colors: Use colors that convey meaning (success, warning, error)
- Typography Hierarchy: Establish clear text size and weight relationships
- Spacing System: Use consistent spacing values throughout
- Component Consistency: Ensure similar components look and behave similarly
- Accessibility: Consider contrast ratios and readable font sizes
- Performance: Avoid creating new theme objects unnecessarily
- Documentation: Document your theme system for other developers
This comprehensive theming system allows you to create beautiful, consistent, and adaptive user interfaces that work seamlessly across different devices and user preferences.
β‘ Performance & Best Practices
Json2UI is designed for high performance and scalability. This section covers optimization techniques, best practices, and performance benchmarks to help you build efficient applications.
Performance Benchmarks
Based on our comprehensive test suite with 326+ tests:
Widget Creation Performance:
- Simple widgets: < 1ms per widget
- Complex nested widgets: < 5ms per widget tree
- Property processing: < 2ms for validation + transformation
- Theme application: < 1ms per themed widget
Memory Usage:
- Base memory footprint: ~2MB
- Per widget overhead: ~50KB
- Cached widget builders: ~100KB total
Build Times:
- Initial build: 50-200ms (depends on complexity)
- Rebuild (same config): 10-50ms
- Theme change: 20-100ms
Widget Creation Optimization
Use Widget Caching for Repeated Configurations
class WidgetCache {
static final Map<String, Widget> _cache = {};
static Widget getOrCreate(String key, Map<String, dynamic> config, BuildContext context) {
if (_cache.containsKey(key)) {
return _cache[key]!;
}
final widget = JsonWidgetFactory.buildFromJson(context, config);
_cache[key] = widget;
return widget;
}
static void clearCache() {
_cache.clear();
}
static void invalidateKey(String key) {
_cache.remove(key);
}
}
// Usage
class OptimizedListView extends StatelessWidget {
final List<Map<String, dynamic>> items;
const OptimizedListView({super.key, required this.items});
@override
Widget build(BuildContext context) {
return ListView.builder(
itemCount: items.length,
itemBuilder: (context, index) {
final item = items[index];
final cacheKey = 'item_${item['id']}';
return WidgetCache.getOrCreate(cacheKey, item, context);
},
);
}
}
Pre-compile Complex Widget Trees
class PrecompiledWidgetFactory {
static final Map<String, JsonWidgetBuilder> _builders = {};
static void precompileBuilder(String type, JsonWidgetBuilder builder) {
_builders[type] = builder;
}
static Widget buildOptimized(BuildContext context, Map<String, dynamic> config) {
final type = config['type'] as String;
if (_builders.containsKey(type)) {
return _builders[type]!.build(
context,
config['properties'] ?? {},
_buildChildren(context, config['children']),
null, // actionHandler
);
}
return JsonWidgetFactory.buildFromJson(context, config);
}
static List<Widget>? _buildChildren(BuildContext context, dynamic children) {
if (children is! List) return null;
return children.map((child) {
if (child is Map<String, dynamic>) {
return buildOptimized(context, child);
}
return const SizedBox.shrink();
}).toList();
}
}
Property Processing Optimization
Batch Property Validation
class BatchPropertyProcessor extends PropertyProcessor {
final List<Map<String, dynamic>> _batchQueue = [];
Timer? _processingTimer;
void addToBatch(Map<String, dynamic> properties) {
_batchQueue.add(properties);
// Debounce processing
_processingTimer?.cancel();
_processingTimer = Timer(const Duration(milliseconds: 16), _processBatch);
}
void _processBatch() {
if (_batchQueue.isEmpty) return;
// Process all queued properties at once
final batch = List.from(_batchQueue);
_batchQueue.clear();
for (final properties in batch) {
processAsync(properties).then((processed) {
// Handle processed properties
_onBatchProcessed(processed);
});
}
}
void _onBatchProcessed(Map<String, dynamic> processed) {
// Notify listeners or update UI
}
}
Optimize Async Property Processing
class OptimizedPropertyProcessor extends PropertyProcessor {
final Map<String, Future<Map<String, dynamic>>> _processingCache = {};
@override
Future<Map<String, dynamic>> processAsync(Map<String, dynamic> properties) async {
final cacheKey = _generateCacheKey(properties);
if (_processingCache.containsKey(cacheKey)) {
return _processingCache[cacheKey]!;
}
final future = _processAsyncInternal(properties);
_processingCache[cacheKey] = future;
// Clean up cache after processing
future.whenComplete(() {
Future.delayed(const Duration(seconds: 30), () {
_processingCache.remove(cacheKey);
});
});
return future;
}
Future<Map<String, dynamic>> _processAsyncInternal(Map<String, dynamic> properties) async {
// Parallel processing of independent validations
final validationFutures = <Future>[];
final transformationFutures = <Future>[];
// Group validations by dependency
for (final validator in _validators.entries) {
if (_canProcessInParallel(validator.key, properties)) {
validationFutures.add(_runValidator(validator.key, validator.value, properties));
}
}
// Wait for all parallel validations
await Future.wait(validationFutures);
// Then run transformations
for (final transformer in _transformers.entries) {
transformationFutures.add(_runTransformer(transformer.key, transformer.value, properties));
}
await Future.wait(transformationFutures);
// Apply middleware
return _applyMiddleware(properties);
}
String _generateCacheKey(Map<String, dynamic> properties) {
// Create a deterministic cache key
final sortedKeys = properties.keys.toList()..sort();
final keyValues = sortedKeys.map((key) => '$key:${properties[key]}');
return keyValues.join('|');
}
bool _canProcessInParallel(String property, Map<String, dynamic> properties) {
// Check if this property depends on others that haven't been processed
return true; // Simplified - implement based on your dependency graph
}
}
Memory Management Best Practices
Implement Widget Pooling
class WidgetPool {
final Map<String, List<Widget>> _pool = {};
final int _maxPoolSize;
WidgetPool({int maxPoolSize = 100}) : _maxPoolSize = maxPoolSize;
Widget? getPooledWidget(String type) {
final pool = _pool[type];
if (pool != null && pool.isNotEmpty) {
return pool.removeLast();
}
return null;
}
void returnToPool(String type, Widget widget) {
final pool = _pool.putIfAbsent(type, () => []);
if (pool.length < _maxPoolSize) {
pool.add(widget);
}
}
void clearPool() {
_pool.clear();
}
}
Optimize Image Loading
class OptimizedImageBuilder extends JsonWidgetBuilder {
final Map<String, ImageProvider> _imageCache = {};
final Map<String, Future<ui.Image>> _loadingImages = {};
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
final imageUrl = properties['imageUrl'] as String?;
if (imageUrl == null) return const SizedBox.shrink();
return FutureBuilder<ui.Image>(
future: _getOrLoadImage(imageUrl),
builder: (context, snapshot) {
if (snapshot.connectionState == ConnectionState.waiting) {
return _buildPlaceholder(properties);
}
if (snapshot.hasError) {
return _buildErrorWidget(properties, snapshot.error);
}
return RawImage(
image: snapshot.data,
fit: BoxFit.cover,
);
},
);
}
Future<ui.Image> _getOrLoadImage(String url) async {
if (_loadingImages.containsKey(url)) {
return _loadingImages[url]!;
}
final future = _loadImage(url);
_loadingImages[url] = future;
return future;
}
Future<ui.Image> _loadImage(String url) async {
final response = await http.get(Uri.parse(url));
final bytes = response.bodyBytes;
final codec = await ui.instantiateImageCodec(bytes);
final frame = await codec.getNextFrame();
// Cache the loaded image
_imageCache[url] = MemoryImage(bytes);
return frame.image;
}
Widget _buildPlaceholder(Map<String, dynamic> properties) {
return Container(
color: Colors.grey.shade200,
child: const Center(
child: CircularProgressIndicator(),
),
);
}
Widget _buildErrorWidget(Map<String, dynamic> properties, Object? error) {
return Container(
color: Colors.grey.shade200,
child: const Center(
child: Icon(Icons.broken_image, color: Colors.grey),
),
);
}
}
Responsive Design Optimization
Implement Virtual Scrolling for Large Lists
class VirtualizedListBuilder extends JsonWidgetBuilder {
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
final items = properties['items'] as List<dynamic>? ?? [];
final itemHeight = properties['itemHeight'] as double? ?? 50.0;
final viewportHeight = properties['viewportHeight'] as double? ?? 400.0;
return VirtualizedListView(
items: items,
itemHeight: itemHeight,
viewportHeight: viewportHeight,
itemBuilder: (context, index, item) {
return JsonWidgetFactory.buildFromJson(
context,
item as Map<String, dynamic>,
);
},
);
}
}
class VirtualizedListView extends StatefulWidget {
final List<dynamic> items;
final double itemHeight;
final double viewportHeight;
final Widget Function(BuildContext, int, dynamic) itemBuilder;
const VirtualizedListView({
super.key,
required this.items,
required this.itemHeight,
required this.viewportHeight,
required this.itemBuilder,
});
@override
State<VirtualizedListView> createState() => _VirtualizedListViewState();
}
class _VirtualizedListViewState extends State<VirtualizedListView> {
final ScrollController _scrollController = ScrollController();
double _scrollOffset = 0.0;
@override
void initState() {
super.initState();
_scrollController.addListener(_onScroll);
}
@override
void dispose() {
_scrollController.dispose();
super.dispose();
}
void _onScroll() {
setState(() {
_scrollOffset = _scrollController.offset;
});
}
@override
Widget build(BuildContext context) {
final startIndex = (_scrollOffset / widget.itemHeight).floor();
final endIndex = startIndex + (widget.viewportHeight / widget.itemHeight).ceil() + 1;
final visibleItems = widget.items.sublist(
startIndex.clamp(0, widget.items.length),
endIndex.clamp(0, widget.items.length),
);
return SizedBox(
height: widget.viewportHeight,
child: ListView.builder(
controller: _scrollController,
itemCount: visibleItems.length,
itemBuilder: (context, index) {
final actualIndex = startIndex + index;
return SizedBox(
height: widget.itemHeight,
child: widget.itemBuilder(context, actualIndex, visibleItems[index]),
);
},
),
);
}
}
Animation Performance
Use Efficient Animation Controllers
class OptimizedAnimationBuilder extends JsonWidgetBuilder {
final Map<String, AnimationController> _controllerCache = {};
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
final animationId = properties['id'] as String? ?? 'default';
final duration = properties['duration'] as int? ?? 300;
return _OptimizedAnimatedWidget(
animationId: animationId,
duration: duration,
properties: properties,
children: children,
actionHandler: actionHandler,
);
}
}
class _OptimizedAnimatedWidget extends StatefulWidget {
final String animationId;
final int duration;
final Map<String, dynamic> properties;
final List<Widget>? children;
final ActionHandler? actionHandler;
const _OptimizedAnimatedWidget({
required this.animationId,
required this.duration,
required this.properties,
this.children,
this.actionHandler,
});
@override
State<_OptimizedAnimatedWidget> createState() => _OptimizedAnimatedWidgetState();
}
class _OptimizedAnimatedWidgetState extends State<_OptimizedAnimatedWidget>
with SingleTickerProviderStateMixin {
late AnimationController _controller;
late Animation<double> _animation;
@override
void initState() {
super.initState();
_controller = AnimationController(
duration: Duration(milliseconds: widget.duration),
vsync: this,
);
_animation = Tween<double>(
begin: 0.0,
end: 1.0,
).animate(CurvedAnimation(
parent: _controller,
curve: Curves.easeOut,
));
// Auto-start animation
_controller.forward();
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return AnimatedBuilder(
animation: _animation,
builder: (context, child) {
return Opacity(
opacity: _animation.value,
child: Transform.translate(
offset: Offset(0, 20 * (1 - _animation.value)),
child: JsonWidgetFactory.buildFromJson(
context,
widget.properties,
),
),
);
},
);
}
}
Best Practices Summary
1. Caching Strategy
- Cache frequently used widget configurations
- Implement smart cache invalidation
- Use memory-efficient caching for images and assets
2. Async Processing
- Batch similar operations
- Use parallel processing where possible
- Implement proper error handling and fallbacks
3. Memory Management
- Pool reusable widgets
- Clean up resources properly
- Monitor memory usage in production
4. Performance Monitoring
class PerformanceMonitor {
static final Map<String, List<Duration>> _metrics = {};
static void trackOperation(String operation, Duration duration) {
_metrics.putIfAbsent(operation, () => []).add(duration);
// Keep only last 100 measurements
if (_metrics[operation]!.length > 100) {
_metrics[operation]!.removeAt(0);
}
}
static Map<String, double> getAverageMetrics() {
return _metrics.map((key, durations) {
final average = durations.fold<Duration>(
Duration.zero,
(sum, duration) => sum + duration,
);
return MapEntry(key, average.inMilliseconds / durations.length);
});
}
static void logPerformanceReport() {
final metrics = getAverageMetrics();
debugPrint('=== Performance Report ===');
metrics.forEach((operation, avgMs) {
debugPrint('$operation: ${avgMs.toStringAsFixed(2)}ms average');
});
}
}
// Usage
Future<Widget> buildWidgetWithTracking(BuildContext context, Map<String, dynamic> config) async {
final stopwatch = Stopwatch()..start();
try {
final widget = await JsonWidgetFactory.buildFromJson(context, config);
PerformanceMonitor.trackOperation('widget_build', stopwatch.elapsed);
return widget;
} catch (e) {
PerformanceMonitor.trackOperation('widget_build_error', stopwatch.elapsed);
rethrow;
}
}
5. Code Splitting and Lazy Loading
class LazyWidgetBuilder extends JsonWidgetBuilder {
final Map<String, Future<JsonWidgetBuilder>> _lazyBuilders = {};
void registerLazyBuilder(String type, Future<JsonWidgetBuilder> Function() builderFactory) {
_lazyBuilders[type] = builderFactory().then((builder) {
JsonWidgetRegistry.register(type, builder);
return builder;
});
}
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
final type = properties['type'] as String;
if (_lazyBuilders.containsKey(type)) {
return FutureBuilder<JsonWidgetBuilder>(
future: _lazyBuilders[type],
builder: (context, snapshot) {
if (snapshot.connectionState == ConnectionState.waiting) {
return const CircularProgressIndicator();
}
if (snapshot.hasError) {
return Text('Error loading widget: ${snapshot.error}');
}
return snapshot.data!.build(context, properties, children, actionHandler);
},
);
}
return JsonWidgetFactory.buildFromJson(context, properties);
}
}
6. Testing Performance
void main() {
group('Performance Tests', () {
test('Widget creation performance', () async {
final config = {
'type': 'container',
'properties': {
'child': {
'type': 'text',
'properties': {'data': 'Test'},
},
},
};
final stopwatch = Stopwatch()..start();
for (int i = 0; i < 1000; i++) {
await JsonWidgetFactory.buildFromJson(
TestWidgetsFlutterBinding.ensureInitialized().rootElement!,
config,
);
}
stopwatch.stop();
final avgTime = stopwatch.elapsedMilliseconds / 1000;
expect(avgTime, lessThan(5)); // Should be less than 5ms per widget
});
test('Memory leak detection', () async {
// Test for memory leaks in widget creation
// This would require integration with a memory profiling tool
});
});
}
Following these performance best practices will ensure your Json2UI applications remain fast, responsive, and memory-efficient even with complex widget trees and large datasets.
- Custom Widgets: Creating and registering custom widget builders
- Responsive Design: Using breakpoints for adaptive layouts
- Property Processing: Advanced property validation and transformation
- Animation: Smooth animations and transitions
- Theming: Integration with Flutter themes
π§ Troubleshooting
This section covers common issues and their solutions when working with Json2UI.
Widget Not Rendering
Issue: Widget type not recognized
Symptoms:
- Widget renders as empty space or throws an exception
- Console shows:
Unknown widget type: 'custom_widget'
Solutions:
- Check widget registration:
// Ensure your custom widget is registered
JsonWidgetRegistry.register('custom_widget', CustomWidgetBuilder());
- Verify widget type spelling:
// Check for typos in JSON configuration
{
'type': 'custom_widget', // Make sure this matches registration
'properties': { /* ... */ }
}
- Check import statements:
import 'package:json2ui/json2ui.dart';
import 'package:your_package/custom_widget_builder.dart';
Issue: Properties not applied correctly
Symptoms:
- Widget renders but ignores some properties
- Layout doesn't match expectations
Solutions:
- Validate property names:
// Common mistakes
{
'type': 'container',
'properties': {
'color': Colors.blue, // Correct
'colour': Colors.blue, // Wrong - British spelling not supported
}
}
- Check property types:
// Ensure correct data types
{
'type': 'container',
'properties': {
'width': 200.0, // double
'height': 100.0, // double
'color': '#FF0000', // String for hex colors
}
}
Property Processing Issues
Issue: Property validation fails
Symptoms:
- Widget throws
PropertyValidationException - Console shows validation error messages
Solutions:
- Check property validators:
// Add proper validation
final processor = PropertyProcessor()
..addValidator('email', (value) {
if (value is! String) return false;
return RegExp(r'^[^@]+@[^@]+\.[^@]+$').hasMatch(value);
});
- Handle validation errors gracefully:
try {
final widget = await JsonWidgetFactory.buildFromJson(context, config);
return widget;
} catch (e) {
if (e is PropertyValidationException) {
return ErrorWidget('Invalid configuration: ${e.message}');
}
rethrow;
}
Issue: Async property processing hangs
Symptoms:
- Widget never renders
- UI shows loading indicator indefinitely
Solutions:
- Add timeouts to async operations:
final processor = PropertyProcessor()
..addAsyncTransformer('imageUrl', (value) async {
final timeout = const Duration(seconds: 10);
final response = await http.get(Uri.parse(value as String))
.timeout(timeout);
return response.statusCode == 200 ? value : null;
});
- Provide fallback values:
final processor = PropertyProcessor()
..addDefault('imageUrl', 'https://example.com/placeholder.png')
..addAsyncTransformer('imageUrl', (value) async {
try {
// Attempt to load image
return await validateImageUrl(value);
} catch (e) {
// Return default on failure
return processor.getDefault('imageUrl');
}
});
Responsive Design Problems
Issue: Breakpoints not working as expected
Symptoms:
- Layout doesn't change at expected screen sizes
- Responsive properties not applied correctly
Solutions:
- Verify breakpoint configuration:
final theme = JsonTheme(
breakpoints: JsonBreakpoints(
xs: 576, // Mobile
sm: 768, // Tablet
md: 992, // Small desktop
lg: 1200, // Large desktop
xl: 1400, // Extra large
),
);
- Check responsive value syntax:
{
'type': 'container',
'properties': {
'width': {
'xs': '100%', // Mobile: full width
'sm': '50%', // Tablet: half width
'md': '33.33%', // Desktop: third width
},
}
}
- Test on different screen sizes:
// Use Flutter's Device Preview package for testing
// or resize your app window to test breakpoints
Theming Issues
Issue: Theme not applied to custom widgets
Symptoms:
- Custom widgets ignore theme settings
- Inconsistent styling across widgets
Solutions:
- Implement theme awareness in custom widgets:
class ThemedCustomWidget extends JsonWidgetBuilder {
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
final theme = JsonWidgetFactory.getTheme();
return Container(
color: theme.cardTheme?.backgroundColor ?? Colors.white,
padding: theme.cardTheme?.padding ?? const EdgeInsets.all(16),
child: Text(
properties['title'],
style: theme.headline2?.copyWith(
color: theme.onSurfaceColor,
),
),
);
}
}
- Use theme variables in JSON:
{
'type': 'container',
'properties': {
'color': '\${theme.primaryColor}',
'padding': '\${theme.spacing.md}',
}
}
Performance Issues
Issue: Slow widget rendering
Symptoms:
- App feels sluggish
- High CPU usage during widget creation
Solutions:
- Implement widget caching:
class CachedWidgetBuilder extends JsonWidgetBuilder {
static final Map<String, Widget> _cache = {};
@override
Widget build(BuildContext context, Map<String, dynamic> properties,
List<Widget>? children, ActionHandler? actionHandler) {
final cacheKey = _generateCacheKey(properties);
if (_cache.containsKey(cacheKey)) {
return _cache[cacheKey]!;
}
final widget = _buildWidget(context, properties, children, actionHandler);
_cache[cacheKey] = widget;
return widget;
}
String _generateCacheKey(Map<String, dynamic> properties) {
// Generate unique key based on properties
return properties.toString();
}
}
- Optimize property processing:
// Use parallel processing for independent validations
final processor = PropertyProcessor()
..addAsyncTransformer('data', (value) async {
final results = await Future.wait([
_fetchUserData(value),
_fetchProductData(value),
_fetchAnalyticsData(value),
]);
return results;
});
- Profile your app:
// Use Flutter DevTools for performance profiling
// Check the Timeline view for bottlenecks
// Use the Memory view to detect leaks
Memory Leaks
Issue: Memory usage keeps growing
Symptoms:
- App memory usage increases over time
- Performance degrades during extended use
Solutions:
- Clean up resources properly:
class ResourceAwareWidget extends StatefulWidget {
@override
State<ResourceAwareWidget> createState() => _ResourceAwareWidgetState();
}
class _ResourceAwareWidgetState extends State<ResourceAwareWidget> {
StreamSubscription? _subscription;
Timer? _timer;
@override
void initState() {
super.initState();
_subscription = someStream.listen((event) {
// Handle event
});
_timer = Timer.periodic(const Duration(seconds: 1), (_) {
// Periodic task
});
}
@override
void dispose() {
_subscription?.cancel();
_timer?.cancel();
super.dispose();
}
@override
Widget build(BuildContext context) {
// Build widget
}
}
- Use weak references for caches:
class WeakCache {
final Map<String, WeakReference<Widget>> _cache = {};
void put(String key, Widget widget) {
_cache[key] = WeakReference(widget);
}
Widget? get(String key) {
final ref = _cache[key];
if (ref != null && ref.target != null) {
return ref.target;
}
_cache.remove(key);
return null;
}
void clear() {
_cache.clear();
}
}
Build and Compilation Issues
Issue: Package not found
Symptoms:
- Import errors:
Target of URI doesn't exist - Compilation fails with package resolution errors
Solutions:
- Check pubspec.yaml dependencies:
dependencies:
flutter:
sdk: flutter
json2ui: ^1.0.0 # Ensure correct version
dev_dependencies:
flutter_test:
sdk: flutter
- Run pub get:
flutter pub get
# or
flutter packages get
- Check Flutter SDK version compatibility:
environment:
sdk: ">=3.0.0 <4.0.0"
flutter: ">=3.10.0"
Issue: Platform-specific compilation errors
Symptoms:
- Android build fails
- iOS build fails
- Web build fails
Solutions:
- Check platform-specific code:
// Use conditional imports
import 'platform_specific.dart'
if (dart.library.io) 'platform_specific_io.dart'
if (dart.library.html) 'platform_specific_web.dart';
- Update platform configurations:
# android/app/build.gradle
android {
defaultConfig {
minSdkVersion 21
}
}
Action Handler Issues
Issue: Actions not triggering
Symptoms:
- Button taps don't execute expected behavior
- No response to user interactions
Solutions:
- Verify action handler implementation:
class MyWidget extends StatelessWidget {
final ActionHandler? actionHandler;
void _handleAction(String action, Map<String, dynamic> data) {
actionHandler?.call(action, data);
}
@override
Widget build(BuildContext context) {
return ElevatedButton(
onPressed: () => _handleAction('button_pressed', {'id': 'submit'}),
child: const Text('Submit'),
);
}
}
- Check action handler setup:
final widget = JsonWidgetFactory.buildFromJson(
context,
config,
actionHandler: (action, data) {
switch (action) {
case 'button_pressed':
_handleButtonPress(data);
break;
case 'navigation':
_handleNavigation(data);
break;
}
},
);
Testing Issues
Issue: Tests failing unexpectedly
Symptoms:
- Widget tests fail inconsistently
- Mock objects not working correctly
Solutions:
- Use proper test setup:
void main() {
setUpAll(() {
// Initialize test environment
TestWidgetsFlutterBinding.ensureInitialized();
});
testWidgets('Widget renders correctly', (tester) async {
await tester.pumpWidget(
MaterialApp(
home: JsonWidgetFactory.buildFromJson(
tester.element(find.byType(MaterialApp)),
testConfig,
),
),
);
await tester.pumpAndSettle();
expect(find.text('Expected Text'), findsOneWidget);
});
}
- Mock external dependencies:
class MockApiService extends Mock implements ApiService {
@override
Future<Map<String, dynamic>> fetchData(String endpoint) async {
return {'data': 'mocked response'};
}
}
test('Property processor with mocked service', () async {
final mockService = MockApiService();
final processor = PropertyProcessor()
..addAsyncTransformer('apiData', (value) async {
return await mockService.fetchData(value as String);
});
final result = await processor.processAsync({'apiData': 'test'});
expect(result['apiData'], {'data': 'mocked response'});
});
Getting Help
If you encounter an issue not covered here:
- Check the GitHub Issues page for similar problems
- Create a minimal reproduction case
- Include your Flutter version and Json2UI version
- Provide complete error messages and stack traces
- Share your JSON configuration (anonymized if necessary)
Common Error Messages and Solutions
| Error Message | Likely Cause | Solution |
|---|---|---|
Unknown widget type: 'xyz' |
Widget not registered | Register the widget with JsonWidgetRegistry.register() |
PropertyValidationException |
Invalid property value | Check property types and validation rules |
TypeError: null check operator used on a null value |
Missing null check | Add null safety checks in your code |
RenderBox was not laid out |
Layout constraints issue | Check parent widget constraints and sizing |
A RenderFlex overflowed |
Content too large for container | Use scrolling or adjust sizing properties |
The method 'findRenderObject' was called on null |
Widget not mounted | Check widget lifecycle and mounting state |
This troubleshooting guide should help you resolve most common issues. If you continue to experience problems, please don't hesitate to reach out to the community or file an issue on GitHub.
π§ͺ Testing
Json2UI includes comprehensive tests:
# Run all tests
flutter test
# Run with coverage
flutter test --coverage
# Run specific test groups
flutter test test/integration/
flutter test test/processors/
π€ Contributing
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Acknowledgments
- Inspired by Mantine's responsive design system
- Built with Flutter's powerful widget system
- Thanks to the Flutter community for amazing tools and libraries
π Support
- π Issues: GitHub Issues
- π¬ Discussions: GitHub Discussions
- π Documentation: Full API Docs
Made with β€οΈ by the DevGen team
Libraries
- json2ui
- A Flutter package for creating UI components from JSON with theming support