Skip to Content
Getting Started

Getting Started

Get up and running with Primitive UI in your Flutter project in just a few minutes.

What is Primitive UI?

Primitive UI is a Flutter GUI library built entirely from scratch using only primitive components:

  • CustomPaint and Canvas for rendering
  • GestureDetector for user input
  • Custom RenderBox for layout

No high-level widgets like Card, Column, Switch, or Stack are used in the implementation. This makes Primitive UI an excellent educational tool for understanding how Flutter’s rendering engine works under the hood.

Prerequisites

Before you begin, ensure you have:

Required:

  • Flutter SDK >=3.9.2
  • Dart SDK (comes with Flutter)
  • A code editor (VS Code, Android Studio, or IntelliJ IDEA)

Verify Flutter Installation

Check your Flutter installation:

flutter --version

You should see output similar to:

Flutter 3.9.2 • channel stable
Tools • Dart 3.0.0

Installation

Add Primitive UI to Your Project

Since Primitive UI is currently a local package, add it to your pubspec.yaml:

pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  primitive_ui:
    path: ../primitive_ui

Important: Adjust the path to match your project structure. The path is relative to your project’s root directory.

Install Dependencies

Run the following command in your terminal:

flutter pub get

You should see output like:

Running "flutter pub get" in your_project...
Resolving dependencies...
+ primitive_ui 0.0.1 from path ../primitive_ui
Changed 1 dependency!

Import the Library

In your Dart files, import Primitive UI:

lib/main.dart
import 'package:primitive_ui/primitive_ui.dart';

Verify Installation

Create a simple test to verify everything works:

lib/main.dart
import 'package:flutter/material.dart';
import 'package:primitive_ui/primitive_ui.dart';
 
void main() {
  runApp(MyApp());
}
 
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: PrimitiveCard(
            child: Text('Primitive UI Works!'),
          ),
        ),
      ),
    );
  }
}

Run your app:

flutter run

You should see a white card with “Primitive UI Works!” in the center.

First Example

Let’s create a simple settings panel using Primitive UI components:

lib/main.dart
import 'package:flutter/material.dart';
import 'package:primitive_ui/primitive_ui.dart';
 
void main() => runApp(MyApp());
 
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Primitive UI Demo',
      home: SettingsPage(),
    );
  }
}
 
class SettingsPage extends StatefulWidget {
  @override
  State<SettingsPage> createState() => _SettingsPageState();
}
 
class _SettingsPageState extends State<SettingsPage> {
  bool _notificationsEnabled = true;
  bool _darkModeEnabled = false;
 
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Settings')),
      body: Padding(
        padding: EdgeInsets.all(16.0),
        child: VStack(
          spacing: 16.0,
          children: [
            PrimitiveCard(
              elevation: 2.0,
              child: Row(
                mainAxisAlignment: MainAxisAlignment.spaceBetween,
                children: [
                  Text('Notifications'),
                  PrimitiveToggleSwitch(
                    value: _notificationsEnabled,
                    onChanged: (value) {
                      setState(() => _notificationsEnabled = value);
                    },
                  ),
                ],
              ),
            ),
            PrimitiveCard(
              elevation: 2.0,
              child: Row(
                mainAxisAlignment: MainAxisAlignment.spaceBetween,
                children: [
                  Text('Dark Mode'),
                  PrimitiveToggleSwitch(
                    value: _darkModeEnabled,
                    onChanged: (value) {
                      setState(() => _darkModeEnabled = value);
                    },
                  ),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Available Components

Primitive UI includes 4 core components:

UI Components

PrimitiveCard

Container with shadow, rounded corners, and padding

PrimitiveToggleSwitch

Animated toggle switch with smooth transitions

PrimitiveSlider

Slider for selecting a value from a range

PrimitiveCircularProgress

Indeterminate circular progress indicator

Layout Components

VStack

Vertical stack with spacing and alignment

HStack

Horizontal stack with spacing and alignment

ZStack

Layered stack for z-ordering widgets

Quick Reference

Common Patterns

Creating a card:

PrimitiveCard(
  child: Text('Content'),
)

Vertical layout:

VStack(
  spacing: 16.0,
  children: [
    Text('First'),
    Text('Second'),
  ],
)

Layering widgets:

ZStack(
  alignment: Alignment.center,
  children: [
    Container(width: 200, height: 200, color: Colors.blue),
    Icon(Icons.star, size: 50),
  ],
)

Toggle switch:

PrimitiveToggleSwitch(
  value: isEnabled,
  onChanged: (value) => setState(() => isEnabled = value),
)

Next Steps

Now that you have Primitive UI installed, explore the documentation:

📚

Component Documentation

Learn about each component’s API and see examples

💡

Examples

Explore practical examples and common patterns

🏗️

Architecture

Understand how Primitive UI works under the hood

⚙️

Source Code

View the source code on GitHub

Troubleshooting

Package Not Found

If you see Error: Cannot find package 'primitive_ui':

  1. Verify the path in pubspec.yaml is correct
  2. Run flutter pub get
  3. Restart your IDE

Import Errors

If you see “Undefined class” errors:

  1. Ensure you’ve imported: import 'package:primitive_ui/primitive_ui.dart';
  2. Run flutter pub get
  3. Restart the Dart Analysis Server

Shadow Not Rendering

If PrimitiveCard shadows don’t appear:

  1. Add padding around the card to give space for the shadow
  2. Ensure the card isn’t clipped by its parent
  3. Try increasing the elevation value

Getting Help

Need assistance? Here are the best resources:

🐛

Report Issues

Found a bug? Let us know on GitHub

💻

View Examples

Check example code and usage

🧪

Review Tests

See test files for component usage

Ready to learn more? Continue to the Component Documentation or explore the Architecture section.

Last updated on
Basic UsageReleases