colaxy_adaptive_scaffold 0.0.1

A Flutter package for adaptive navigation.

colaxy_adaptive_scaffold

An adaptive scaffold that automatically switches between NavigationBar (bottom) and NavigationRail (side) based on screen aspect ratio.

Features

• Aspect Ratio-Based Adaptation: Automatically switches navigation layout based on screen aspect ratio (width/height)
• Simple API: Just provide a list of navigation items with names, icons, and pages
• Internal State Management: No need to manage selected index yourself
• Customizable Threshold: Configure when the layout switch happens
• Fully Documented: Comprehensive parameter documentation and examples

Getting Started

Add the package to your pubspec.yaml:

dependencies:
  colaxy_adaptive_scaffold:
    git:
      url: https://github.com/normidar/colaxy_adaptive_scaffold.git

Usage

Basic Example

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

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: AdaptiveScaffold(
        items: [
          NavigationItem(
            name: 'Home',
            icon: Icon(Icons.home),
            page: HomePage(),
          ),
          NavigationItem(
            name: 'Search',
            icon: Icon(Icons.search),
            page: SearchPage(),
          ),
          NavigationItem(
            name: 'Settings',
            icon: Icon(Icons.settings),
            page: SettingsPage(),
          ),
        ],
      ),
    );
  }
}

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Home Page'));
  }
}

class SearchPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Search Page'));
  }
}

class SettingsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Settings Page'));
  }
}

Advanced Example with Custom Settings

AdaptiveScaffold(
  items: [
    NavigationItem(
      name: 'Dashboard',
      icon: Icon(Icons.dashboard),
      page: DashboardPage(),
    ),
    NavigationItem(
      name: 'Analytics',
      icon: Icon(Icons.analytics),
      page: AnalyticsPage(),
    ),
  ],
  initialIndex: 0,                    // Start with first item selected
  aspectRatioThreshold: 1.5,          // Use side navigation only on wider screens
  floatingActionButton: FloatingActionButton(
    onPressed: () {},
    child: Icon(Icons.add),
  ),
)

API Reference

AdaptiveScaffold

The main widget that provides adaptive navigation.

Parameters

Required Parameters

• items (List<NavigationItem>): List of navigation items to display. Each item contains:
  • name: Label text for the navigation item
  • icon: Icon widget to display
  • page: Page widget to show when selected

Optional Parameters

• initialIndex (int, default: 0): The initially selected navigation item index

• aspectRatioThreshold (double, default: 1.2): The aspect ratio threshold for switching layouts

  • If width/height >= threshold: Uses NavigationRail (side navigation)
  • If width/height < threshold: Uses NavigationBar (bottom navigation)
  • Common values:
    • 1.0: Switch at square screens
    • 1.2: Switch at slightly landscape screens (default)
    • 1.5: Switch only at wider landscape screens

• floatingActionButton (Widget?): Optional floating action button to display

NavigationItem

A class that defines a navigation destination.

Parameters

• name (String): The label text for this navigation item
• icon (Widget): The icon widget to display (typically an Icon)
• page (Widget): The page widget to display when this item is selected

How It Works

The AdaptiveScaffold calculates the screen's aspect ratio (width / height) and compares it to the aspectRatioThreshold:

• Portrait/Narrow layouts (aspect ratio < threshold): Shows NavigationBar at the bottom
• Landscape/Wide layouts (aspect ratio >= threshold): Shows NavigationRail on the left side

This ensures optimal navigation placement based on the available screen space, rather than just screen width.

License

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