Documentation

Contributing

Learn how to contribute Flutter components to FlockUI. We welcome all contributions!

Welcome to FlockUI

Thank you for considering contributing to FlockUI! We're building an open-source Flutter UI component library, and every contribution — whether it's a new component, a bug fix, or a documentation improvement — helps the community grow.

Prerequisites

ToolVersionPurpose
Node.jsv18+Running the Next.js website
npmv9+Package management
Flutter SDKv3.11+Building component previews
GitAnyVersion control

Contribution Overview

Fork the Repository

Click the Fork button on the FlockUI GitHub page to create a copy under your account.

Clone & Install

Clone your fork, add the upstream remote, and run npm install to set up dependencies.

Create Component Directory

Create registry/<component>/<variant>/ and add your Dart component file.

Register Metadata

Add your component's name, tag, color, and description in lib/component-meta.ts.

Build Preview

Run npm run render -- -Component <name> -Variant <variant> to generate a live preview.

Submit a Pull Request

Push your changes and open a PR. I'll review it and merge it once everything looks good.

Project Structure

Understanding the directory layout will help you navigate the codebase:

Directory Structure
flockui/
├── registry/              # 📦 Flutter component source files
│   ├── button/
│   │   └── default/
│   │       └── button_default.dart
│   └── toast/
│       └── default/
│           └── toast_default.dart
├── renderer/              # 🎨 Flutter web project for previews
│   └── lib/
│       ├── main.dart
│       └── component.dart   # (auto-generated)
├── lib/                   # 🧰 Website utilities
│   ├── component-meta.ts    # Component metadata registry
│   ├── get-component-code.ts
│   └── get-preview-url.ts
├── app/                   # 🌐 Next.js app router pages
├── components/            # 🧩 React components for the website
├── scripts/               # 🔧 Build & preview scripts
└── public/                # 📁 Static assets & built previews

Adding a New Component

1. Create the directory

mkdir -p registry/card/default

2. Create the Dart file

Create registry/card/default/card_default.dart with a PreviewComponent class.

3. Register metadata

Add an entry in lib/component-meta.ts:

card: {
  name: "Cards",
  tag: "Layout",
  color: "bg-flutter-purple/10 text-flutter-purple border-flutter-purple/20",
  description: "A flexible container for grouping related content and actions.",
},

4. Build the preview

npm run render -- -Component card -Variant default

5. Verify

Start npm run dev and visit /components/card to see your component.

Component Template

Every component file should follow this structure with header comments:

component_template.dartDart
// FlockUI Component: Button (Default)
// Description: A versatile button widget with multiple variants...
// Category: Elements
// External Dependencies: none
// Author: Your Name (optional)

import 'package:flutter/material.dart';

class PreviewComponent extends StatefulWidget {
  const PreviewComponent({super.key});

  @override
  State<PreviewComponent> createState() => _PreviewComponentState();
}

class _PreviewComponentState extends State<PreviewComponent> {
  @override
  Widget build(BuildContext context) {
    // Your component widget tree goes here
    return ElevatedButton(
      onPressed: () {},
      child: const Text('Click Me'),
    );
  }
}

Code Rules

  • Class name must be PreviewComponent: Required by the renderer.
  • Use Material 3 widgets: Prefer FilledButton, Card, NavigationBar, etc.
  • Keep it self-contained: The entire component in a single .dart file.
  • Annotate external dependencies: List them in comments at the top of the file.

Naming Conventions

ItemConventionExample
Component directorykebab-casetext-field, bottom-sheet
Variant directorykebab-casedefault, outline, with-icon
Dart filesnake_casetext_field_default.dart
Dart classPascalCasePreviewComponent (always)

Contributing to the Website

This guide focuses on contributing Flutter components. If you'd like to contribute to the Next.js website (docs, blog, design improvements), please reach out to me on LinkedIn or email me at sonukumarhansda61@gmail.com so we can discuss the best approach.

Need Help?

If you have questions or run into issues, open an issue on GitHub or email sonukumarhansda61@gmail.com. We're excited to see what you build! 🚀