Overlayer UI Flutter

A premium, high-fidelity UI overlay controls library for Flutter. Designed for overlay panels, developer tools, and HUD configurations with a sleek, dark-themed, and highly responsive aesthetic.

Features

• Global State Management: Built-in state synchronization using OverlayerState and OverlayerStateProvider with automated persistent storage via shared_preferences.
• High-Fidelity Components:
  • UIButton - A reactive, animated button with custom click interactions.
  • UIToggle - Custom animated toggle switch with hollow/filled states, hover outlines, and middle-click reset options.
  • UISlider - Smooth slider interface with percentage/unit formatting and drag response.
  • UIDropdown - Generic typed dropdown component featuring composites overlay lists and elastic animation indicators.
• Developer Features: Middle-scroll-wheel clicking on controls to reset their values to defaults.

---

Installation

Add overlayer_ui_flutter to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  overlayer_ui_flutter:
    git:
      url: https://github.com/square3ang/overlayer_ui_flutter.git

Or when published to pub.dev:

dependencies:
  overlayer_ui_flutter: ^1.0.0

---

Getting Started

To get started, wrap your sandbox or control panel with OverlayerStateProvider and initialize the state.

1. Initialize and Provide State

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

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData.dark(),
      home: const SettingsPanel(),
    );
  }
}

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

  @override
  State<SettingsPanel> createState() => _SettingsPanelState();
}

class _SettingsPanelState extends State<SettingsPanel> {
  final OverlayerState _state = OverlayerState();

  @override
  Widget build(BuildContext context) {
    return ListenableBuilder(
      listenable: _state,
      builder: (context, child) {
        if (!_state.isInitialized) {
          return const Scaffold(
            body: Center(child: CircularProgressIndicator()),
          );
        }

        return OverlayerStateProvider(
          state: _state,
          child: Scaffold(
            body: Center(
              child: Container(
                width: 450,
                padding: const EdgeInsets.all(24),
                decoration: BoxDecoration(
                  color: const Color(0xFF1E1C28),
                  borderRadius: BorderRadius.circular(16),
                ),
                child: const Column(
                  mainAxisSize: MainAxisSize.min,
                  children: [
                    Text('Settings Overlay', style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold)),
                    SizedBox(height: 20),
                    OverlayControls(),
                  ],
                ),
              ),
            ),
          ),
        );
      },
    );
  }
}

2. Using the Components

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

  @override
  Widget build(BuildContext context) {
    final state = OverlayerStateProvider.of(context);

    return Column(
      children: [


        // Toggle Switch
        UIToggle(
          modelValue: state.active,
          defaultValue: OverlayerDefaults.active,
          label: 'Active Overlay',
          onChanged: (val) => state.active = val,
        ),
        const SizedBox(height: 16),



        // Clickable Button
        UIButton(
          label: 'Reset All',
          onClick: () => state.resetAll(),
        ),
      ],
    );
  }
}

---

Detailed Components

OverlayerState

Handles settings configurations (active, tooltip, middleClickToDefault, fontSize). It automatically manages reading/writing to shared_preferences and triggers widgets to repaint.

UIToggle

A premium toggle button. Supports middle-click resets to defaults. Shows a changed dot if the current state differs from the default value.

UISlider

A customized slider control bar displaying text formatting tags (e.g. 1.20x or percentage representation).

UIDropdown

Provides a composited follower popup layer. Closes upon clicking outside of the dropdown boundaries.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.