๐ FormStack - Dynamic Form Builder for Flutter
The most powerful and flexible form builder for Flutter applications. Create dynamic, responsive forms with minimal code using JSON or Dart objects.
โจ Why Choose FormStack?
- ๐ฏ 20+ Input Types - From simple text fields to complex map location pickers
- ๐จ Multiple Styles - Beautiful, customizable UI components
- ๐ฑ Responsive Design - Works perfectly on all screen sizes
- ๐ง JSON or Dart - Build forms using JSON files or Dart objects
- โก High Performance - Optimized for smooth user experience
- ๐ก๏ธ Built-in Validation - Comprehensive validation with custom error messages
- ๐งฉ Modular Architecture - Easy to extend and customize
- ๐พ Memory Efficient - No memory leaks, proper resource management
๐ฌ Quick Demo
import 'package:formstack/formstack.dart';
// Create a form in just a few lines!
FormStack.api().form(
steps: [
InstructionStep(
title: "Welcome!",
text: "Let's get started with your information",
),
QuestionStep(
title: "Your Name",
inputType: InputType.name,
id: GenericIdentifier(id: "name"),
),
QuestionStep(
title: "Email Address",
inputType: InputType.email,
id: GenericIdentifier(id: "email"),
),
CompletionStep(
title: "Thank You!",
text: "Your information has been submitted",
),
],
).render();
๐ฆ Installation
Add FormStack to your pubspec.yaml
:
dependencies:
formstack: ^latest_version
Then run:
flutter pub get
๐ Quick Start
1. Basic Form Setup
import 'package:flutter/material.dart';
import 'package:formstack/formstack.dart';
class MyForm extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
body: FormStack.api().form(
steps: [
QuestionStep(
title: "What's your name?",
inputType: InputType.name,
id: GenericIdentifier(id: "name"),
),
QuestionStep(
title: "Enter your email",
inputType: InputType.email,
id: GenericIdentifier(id: "email"),
),
],
).render(),
);
}
}
2. Load from JSON
// Load form from JSON file
await FormStack.api().loadFromAsset('assets/my_form.json');
// Render the form
FormStack.api().render()
๐จ Available Input Types
๐ Text Inputs
- Email - Email validation with regex
- Name - Name validation (letters only)
- Password - Secure password input
- Text - Multi-line text input
- Number - Numeric input with validation
๐ Date & Time
- Date - Date picker
- Time - Time picker
- DateTime - Combined date and time picker
โ Choice Inputs
- Single Choice - Radio button selection
- Multiple Choice - Checkbox selection
- Dropdown - Traditional dropdown menu
๐ฏ Special Inputs
- OTP - One-time password input
- Smile Rating - 1-5 star rating slider
- File Upload - File picker with filters
- Dynamic Key-Value - Custom key-value pairs
- HTML Editor - Rich text editor
- Map Location - Interactive map picker
- Avatar - Circular image upload
- Banner - Rectangular image upload
๐จ Styling Options
Component Styles
QuestionStep(
title: "Styled Input",
inputType: InputType.text,
componentsStyle: ComponentsStyle.basic, // or ComponentsStyle.minimal
)
Input Styles
QuestionStep(
title: "Outlined Input",
inputType: InputType.text,
inputStyle: InputStyle.outline, // or InputStyle.underLined, InputStyle.basic
)
Selection Types
QuestionStep(
title: "Choose Option",
inputType: InputType.singleChoice,
selectionType: SelectionType.tick, // or SelectionType.arrow, SelectionType.toggle, SelectionType.dropdown
options: [
Options("option1", "Option 1"),
Options("option2", "Option 2"),
],
)
๐ Form Components
InstructionStep
Display information or instructions to users.
InstructionStep(
title: "Welcome to Our App",
text: "Please complete the following steps",
cancellable: false,
)
QuestionStep
Interactive input fields with validation.
QuestionStep(
title: "Your Question",
text: "Additional description",
inputType: InputType.email,
isOptional: false,
id: GenericIdentifier(id: "unique_id"),
)
CompletionStep
Success/completion screen with animations.
CompletionStep(
title: "Form Completed!",
text: "Thank you for your submission",
onFinish: (result) {
print("Form result: $result");
},
)
NestedStep
Multi-step forms with sub-forms.
NestedStep(
title: "Personal Information",
steps: [
QuestionStep(/* ... */),
QuestionStep(/* ... */),
],
)
๐ก๏ธ Validation
FormStack includes comprehensive validation:
// Built-in validations
ResultFormat.email("Please enter a valid email")
ResultFormat.password("Password must be at least 8 characters")
ResultFormat.notNull("This field is required")
// Custom validation
ResultFormat.custom("Invalid input", (value) => value.length > 5)
// Advanced validations
ResultFormat.phone("Please enter a valid phone number")
ResultFormat.creditCard("Invalid credit card number")
ResultFormat.url("Please enter a valid URL")
ResultFormat.ssn("Invalid Social Security Number")
ResultFormat.zipCode("Invalid ZIP code")
ResultFormat.age("Age must be between 0 and 150")
ResultFormat.percentage("Percentage must be between 0 and 100")
๐ฑ Responsive Design
FormStack automatically adapts to different screen sizes:
QuestionStep(
title: "Responsive Text",
inputType: InputType.text,
display: Display.large, // small, normal, medium, large, extraLarge
)
๐ง Advanced Features
Form Progress Tracking
// Get form completion progress
double progress = FormStack.api().getFormProgress();
print("Form is ${(progress * 100).toInt()}% complete");
// Get detailed statistics
Map<String, dynamic> stats = FormStack.api().getFormStats();
print("Total steps: ${stats['totalSteps']}");
print("Completed: ${stats['completedSteps']}");
Conditional Logic
QuestionStep(
title: "Choose Type",
inputType: InputType.singleChoice,
options: [
Options("personal", "Personal"),
Options("business", "Business"),
],
relevantConditions: [
RelevantCondition(
id: "show_business_fields",
expression: "IN business",
),
],
)
Custom Styling
QuestionStep(
title: "Custom Styled",
inputType: InputType.text,
style: UIStyle(
backgroundColor: Colors.blue,
foregroundColor: Colors.white,
borderRadius: 12.0,
borderColor: Colors.blue.shade300,
),
)
๐ JSON Configuration
Create forms using JSON for easy configuration:
{
"steps": [
{
"type": "InstructionStep",
"title": "Welcome",
"text": "Please complete this form",
"cancellable": false
},
{
"type": "QuestionStep",
"title": "Your Name",
"inputType": "name",
"inputStyle": "outline",
"componentsStyle": "basic",
"isOptional": false,
"id": "name"
},
{
"type": "QuestionStep",
"title": "Email",
"inputType": "email",
"inputStyle": "outline",
"componentsStyle": "basic",
"isOptional": false,
"id": "email"
},
{
"type": "CompletionStep",
"title": "Thank You!",
"text": "Your information has been submitted",
"autoTrigger": true,
"id": "completion"
}
]
}
๐ฏ Real-World Examples
User Registration Form
FormStack.api().form(
steps: [
InstructionStep(
title: "Create Account",
text: "Please provide your information to create an account",
),
QuestionStep(
title: "Full Name",
inputType: InputType.name,
id: GenericIdentifier(id: "full_name"),
),
QuestionStep(
title: "Email Address",
inputType: InputType.email,
id: GenericIdentifier(id: "email"),
),
QuestionStep(
title: "Password",
inputType: InputType.password,
id: GenericIdentifier(id: "password"),
),
QuestionStep(
title: "Phone Number",
inputType: InputType.number,
id: GenericIdentifier(id: "phone"),
),
CompletionStep(
title: "Account Created!",
text: "Welcome to our platform",
onFinish: (result) {
// Handle registration
print("User registered: $result");
},
),
],
).render();
Survey Form
FormStack.api().form(
steps: [
InstructionStep(
title: "Customer Survey",
text: "Help us improve our service",
),
QuestionStep(
title: "How satisfied are you?",
inputType: InputType.smile,
id: GenericIdentifier(id: "satisfaction"),
),
QuestionStep(
title: "What features do you use?",
inputType: InputType.multipleChoice,
selectionType: SelectionType.tick,
options: [
Options("feature1", "Feature 1"),
Options("feature2", "Feature 2"),
Options("feature3", "Feature 3"),
],
id: GenericIdentifier(id: "features"),
),
QuestionStep(
title: "Additional Comments",
inputType: InputType.text,
numberOfLines: 3,
id: GenericIdentifier(id: "comments"),
),
],
).render();
๐๏ธ Architecture
FormStack follows a modular architecture:
lib/
โโโ src/
โ โโโ core/ # Core form logic
โ โโโ ui/ # UI components
โ โ โโโ views/ # Form views
โ โ โโโ input/ # Input field widgets
โ โโโ result/ # Validation and result handling
โ โโโ step/ # Step definitions
โ โโโ utils/ # Utility functions
๐ง Customization
Custom Input Types
// Create custom input widgets by extending BaseStepView
class CustomInputWidget extends BaseStepView<QuestionStep> {
// Implementation
}
Custom Validation
// Create custom validation rules
ResultFormat.custom("Custom error", (value) {
return value.contains("@") && value.length > 5;
})
๐ Performance
FormStack is optimized for performance:
- Memory Efficient: Proper disposal of controllers and resources
- Lazy Loading: Components load only when needed
- Optimized Rebuilds: Minimal widget rebuilds
- Caching: Form state caching for better performance
๐งช Testing
FormStack includes comprehensive testing utilities:
// Test form validation
test('email validation', () {
expect('test@example.com'.isValidEmail(), true);
expect('invalid-email'.isValidEmail(), false);
});
// Test form completion
test('form completion', () {
FormStack.api().form(/* ... */);
expect(FormStack.api().isFormCompleted(), false);
});
๐ค Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
git clone https://github.com/your-org/formstack.git
cd formstack
flutter pub get
flutter test
๐ Documentation
๐ Support
- ๐ Documentation
- ๐ Issue Tracker
- ๐ฌ Discussions
- ๐ง Email Support
๐ License
FormStack is licensed under the MIT License. See LICENSE for details.
๐ Acknowledgments
- Flutter team for the amazing framework
- Community contributors
- All the developers who use FormStack