Skip to main content

ui_guard 1.2.0 copy "ui_guard: ^1.2.0" to clipboard
ui_guard: ^1.2.0 copied to clipboard

Easily manage role, permission, and condition-based access control in Flutter UIs — entirely in Dart.

UI Guard Package

ui_guard

Pub Version Build GitHub Stars Flutter Website

Widgets that make role, permission, condition, policy, and time-based UI control simple, scalable, and flexible.
Built entirely in Dart to help you create smarter, access-aware Flutter applications.

✨ ui_guard works seamlessly with any role management logic or state management approach.


🔐 Why use ui_guard? #

In many Flutter applications, you need to control access to certain parts of the UI.

For example:

  • Show admin settings only to administrators
  • Display upgrade buttons for guest or free users
  • Hide actions when a user does not have the required permission
  • Enable UI only when multiple access conditions are satisfied
  • Reuse the same authorization rules across multiple screens
  • Display UI only during a specific start/end time
  • Enable features according to cron-style schedules
  • React automatically when roles or permissions change
  • Diagnose exactly why access was denied

ui_guard makes these scenarios simple and declarative using Dart.


✨ Features #

  • ✅ Guard widgets or entire screens based on roles
  • 🔑 Permission-based access control
  • 🧩 Combine roles, permissions, and runtime conditions
  • ♻️ Reusable authorization policies with AccessPolicy
  • 🔄 Reactive role and permission updates with GuardNotifier
  • 🔍 Access diagnostics with AccessDecision
  • 🧪 Developer override mode for development and testing
  • 📦 Pure Dart — no platform-specific dependencies
  • ♻️ Works with any state management approach
  • ⏱️ Start/end time-based UI control
  • 🕒 Cron-style scheduled UI access
  • 🌍 Optional UTC schedule evaluation
  • 📱 Responsive and device-based UI control with DeviceTypeGuard
  • ⚡ Asynchronous role loading with AsyncGuard (APIs, Secure Storage, Firebase/Auth)
  • 🔔 Access decision callbacks for logging and debugging

📦 Installation #

Add ui_guard to your pubspec.yaml:

dependencies:
  ui_guard: ^1.2.0

Then run:

flutter pub get

Import the package:

import 'package:ui_guard/ui_guard.dart';

🚀 Quick Start #

Use GuardNotifier when you want the UI to rebuild automatically after role or permission updates.

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

final guard = GuardNotifier()
  ..setUserRoles(['guest'])
  ..setUserPermissions([]);

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

  @override
  Widget build(BuildContext context) {
    return AccessGuard(
      guard: guard,
      rebuildListenable: guard,
      requiredRoles: const ['admin'],
      builder: (_) => const Text('Admin content'),
      fallbackBuilder: (_) => const Text('Access denied'),
    );
  }
}

When the roles or permissions inside GuardNotifier change, widgets using:

rebuildListenable: guard

can automatically rebuild.


🧭 Which Widget Should You Use? #

Need Widget
Show/hide a full section or page by role AccessGuard
Show/hide a small inline widget by role RoleBasedView
Require roles + permissions + runtime condition CombinedGuard
Reuse named authorization rules across screens PolicyGuard + AccessPolicy
Enable content only in a start/end time window TimedAccessGuard
Enable content using a cron schedule ScheduleGuard
Show/hide UI based on device type / screen size DeviceTypeGuard
Load roles asynchronously from API / storage AsyncGuard

🧠 Core API #

🔹 1. Define Access State #

ui_guard provides both non-reactive and reactive guard state.

Basic — Guard #

Use Guard when automatic UI rebuilding is not required.

final guard = Guard();

guard.setUserRoles(['admin']);
guard.setUserPermissions(['users.edit']);

You can access the current roles:

print(guard.currentRoles);

Reactive — GuardNotifier #

For Flutter UI, GuardNotifier is recommended when roles or permissions can change while the application is running.

final guard = GuardNotifier();

guard.setUserRoles(['admin']);
guard.setUserPermissions(['users.edit']);

Use it with:

rebuildListenable: guard

Example:

AccessGuard(
  guard: guard,
  rebuildListenable: guard,
  requiredRoles: const ['admin'],
  builder: (_) => const Text('Admin Panel'),
  fallbackBuilder: (_) => const Text('Access Denied'),
);

🔐 Role-Based Access #

🔹 2. AccessGuard #

Use AccessGuard when you want to protect a complete widget, section, or page.

AccessGuard(
  guard: guard,
  rebuildListenable: guard,
  requiredRoles: const ['admin'],
  builder: (_) => const AdminPanel(),
  fallbackBuilder: (_) => const Text('No access'),
);

If you are using the non-reactive Guard, simply remove:

rebuildListenable: guard

Example:

AccessGuard(
  guard: guard,
  requiredRoles: const ['admin'],
  builder: (_) => const Text('Admin Panel'),
  fallbackBuilder: (_) => const Text('Access Denied'),
);

🔹 3. RoleBasedView #

Use RoleBasedView when you need to show or hide a smaller inline widget.

RoleBasedView(
  guard: guard,
  rebuildListenable: guard,
  requiredRoles: const ['guest'],
  child: const Text('Guest banner'),
  fallback: const SizedBox.shrink(),
);

Another example:

RoleBasedView(
  guard: guard,
  requiredRoles: const ['admin', 'moderator'],
  child: const Text('Admin & Moderator Content'),
  fallback: const Text(
    'You do not have permission to view this content.',
  ),
);

🔹 4. RoleGuard #

RoleGuard provides utility methods for common role checks.

RoleGuard.hasAnyRole(
  ['admin'],
  ['admin', 'user'],
); // true
RoleGuard.hasAllRoles(
  ['admin', 'editor'],
  ['admin'],
);

Use these utilities when you need role checking outside guard widgets.


🧩 Combined Access Conditions #

🔹 5. CombinedGuard #

Use CombinedGuard when access depends on multiple requirements.

It can combine:

  • Roles
  • Permissions
  • Runtime conditions

Example:

CombinedGuard(
  guard: guard,
  rebuildListenable: guard,
  requiredRoles: const ['manager'],
  requiredPermissions: const ['team.edit'],
  condition: () => isInternalMode,
  builder: (_) => const TeamEditor(),
  fallbackBuilder: (_) => const Text('Requirements not met'),
);

This is useful when a role alone is not enough to determine whether content should be available.

For example:

CombinedGuard(
  guard: guard,
  requiredRoles: const ['manager'],
  requiredPermissions: const ['edit_team'],
  condition: () => organization.isInternalMode,
  builder: (_) => const TeamEditor(),
  fallbackBuilder: (_) => const Text('Access Restricted'),
);

♻️ Reusable Access Policies #

🔹 6. AccessPolicy + PolicyGuard #

When the same authorization rule is used in multiple places, define it once as an AccessPolicy.

const manageUsersPolicy = AccessPolicy(
  name: 'manage_users',
  requiredRoles: ['admin'],
  requiredPermissions: ['users.edit'],
);

Then reuse the policy:

PolicyGuard(
  guard: guard,
  rebuildListenable: guard,
  policy: manageUsersPolicy,
  builder: (_) => const Text('User manager'),
  fallbackBuilder: (_) => const Text('No access'),
);

This keeps authorization rules centralized and avoids repeating the same role and permission requirements across your application.

Example use cases include:

  • User management
  • Payment administration
  • Moderator tools
  • Organization settings
  • Restricted reports
  • Feature management

🔍 Access Diagnostics #

🔹 7. AccessDecision #

Sometimes hiding a widget is not enough — you also need to understand why access was denied.

The onDecision callback provides an AccessDecision.

It can include information such as:

  • allowed
  • missingRoles
  • missingPermissions
  • failedCondition
  • reasonCode

Example:

CombinedGuard(
  guard: guard,
  requiredRoles: const ['manager'],
  onDecision: (decision) {
    if (!decision.allowed) {
      debugPrint('Missing roles: ${decision.missingRoles}');
      debugPrint(
        'Missing permissions: ${decision.missingPermissions}',
      );
      debugPrint(
        'Failed condition: ${decision.failedCondition}',
      );
      debugPrint('Reason code: ${decision.reasonCode}');
    }
  },
  builder: (_) => const Text('Manager area'),
  fallbackBuilder: (_) => const Text('Denied'),
);

This is especially useful for:

  • Debugging authorization problems
  • Analytics
  • Logging
  • Access auditing
  • Development diagnostics

🧪 Developer Override Mode #

During development or automated/manual testing, you may temporarily bypass guard restrictions.

GuardConfig.developerOverrideEnabled = true;

When enabled, guard checks are bypassed.

⚠️ Developer override should only be used during development or testing.

Before production, make sure it is disabled:

GuardConfig.developerOverrideEnabled = false;

⏱️ Time-Based Access #

🔹 8. TimedAccessGuard #

Use TimedAccessGuard when content should only be available between a start and end time.

Ideal for:

  • 🎁 Limited-time offers
  • ⚡ Flash sales
  • 🧪 Beta or trial features
  • 🔧 Maintenance notices
  • 📅 Event-specific content
  • 🛍️ Daily or weekly deals
  • 📢 Time-based announcements
  • 🏢 Business-hour features

Example:

TimedAccessGuard(
  start: DateTime(2026, 3, 29, 9),
  end: DateTime(2026, 3, 29, 18),
  checkInterval: const Duration(seconds: 1),
  onTimeUpdate: (remaining) {
    debugPrint(
      'Remaining: ${remaining.inSeconds}s',
    );
  },
  builder: (_) => const Text('Offer active'),
  fallbackBuilder: (_) => const Text('Offer closed'),
);

Another example:

TimedAccessGuard(
  start: DateTime(2026, 7, 18, 9),
  end: DateTime(2026, 7, 18, 13),
  checkInterval: const Duration(seconds: 1),
  onTimeUpdate: (remaining) {
    debugPrint(
      '⏱️ Time left: ${remaining.inSeconds}s',
    );
  },
  builder: (_) => const PromoBanner(),
  fallbackBuilder: (_) => const SizedBox.shrink(),
);

🕒 Scheduled Access with ScheduleGuard #

ScheduleGuard controls UI visibility using cron-style schedules.

Example:

ScheduleGuard(
  schedule: '*/15 9-17 * * MON-FRI',
  useUtc: true,
  checkInterval: const Duration(minutes: 1),
  builder: (_) => const Text('Business hours'),
  fallbackBuilder: (_) => const Text('Outside business hours'),
);

Another example:

ScheduleGuard(
  schedule: '0 9 * * 1-5',
  builder: (_) => const Text('Business is open!'),
  fallbackBuilder: (_) => const Text('Closed right now.'),
);

🧠 How Cron Scheduling Works #

ScheduleGuard supports the standard 5-field cron format:

minute hour day month weekday

Cron Schedule Diagram

Supported cron capabilities #

  • Wildcards
*
  • Lists
1,2,3
  • Ranges
1-5
  • Steps
*/5
  • Month aliases
JAN
FEB
MAR
  • Day aliases
MON-FRI
  • Cron macros such as:
@daily
@weekly
@hourly

The guard can automatically re-evaluate according to the provided:

checkInterval

You can also choose whether scheduling should be evaluated using UTC:

useUtc: true

🕒 ScheduleGuard Use Cases #

ScheduleGuard can be useful for:

  • 🕘 Enable features during business hours
  • 🏷️ Display promotional banners during selected hours
  • 🛠️ Hide functionality during maintenance windows
  • ⏰ Enable actions only at specific scheduled times
  • 📢 Display scheduled announcements
  • 📅 Enable weekday-only functionality
  • 🛒 Run time-limited promotions
  • 💬 Enable customer support/chat during office hours

📱 Device & Screen-Based Access with DeviceTypeGuard #

DeviceTypeGuard shows or hides UI elements based on the device type and screen size the app is running on.

✨ Benefits & Use Cases #

  • 📱 Show a simplified layout on phones, and an advanced one on tablets or desktops
  • 🌐 Hide certain features on web (e.g., camera, hardware-specific tools) or enable web-only controls
  • 📐 Conditional rendering of widgets based on responsive screen breakpoints
  • 💻 Platform-specific UI gating (Android, iOS, macOS, Windows, Linux, Web)
  • 🎨 Supports responsive design logic directly in your widget tree

🔧 Example: Responsive Layout (Issue #9 Planned API) #

DeviceTypeGuard(
  allowedDevices: ['mobile', 'tablet'],
  builder: (_) => const MobileView(),
  fallbackBuilder: (_) => const DesktopView(),
);

🔧 Example: Using DeviceType Enum #

DeviceTypeGuard(
  allowedDevices: [DeviceType.desktop, DeviceType.web],
  builder: (_) => const DesktopOrWebHeader(),
  fallbackBuilder: (_) => const MobileHeader(),
);

🔧 Example: Custom Breakpoints & Overrides #

DeviceTypeGuard(
  allowedDevices: const ['tablet', 'desktop'],
  breakpoints: const DeviceBreakpoints(
    mobileBreakpoint: 500,
    tabletBreakpoint: 900,
  ),
  builder: (_) => const ExpandedDashboard(),
  fallbackBuilder: (_) => const CompactDashboard(),
);

⚡ Asynchronous Role Loading with AsyncGuard #

AsyncGuard allows ui_guard to work seamlessly when user roles or permissions are not available immediately — such as when fetching from:

  • 🔐 Secure storage / SharedPreferences
  • 🌐 Remote backend REST / GraphQL APIs
  • 🔥 Firebase Auth / Supabase / OAuth identity providers

🔧 Example: Issue #5 Planned API #

AsyncGuard(
  roleFuture: loadUserRolesFromServer(),
  builder: (context, roles) => AccessGuard(
    guard: Guard()..setUserRoles(roles),
    requiredRoles: const ['admin'],
    builder: (_) => const Text("Admin Dashboard"),
    fallbackBuilder: (_) => const Text("Access Denied"),
  ),
);

🔧 Example: Direct Role Gating with AsyncGuard.guard #

AsyncGuard.guard(
  roleFuture: loadUserRolesFromServer(),
  requiredRoles: const ['admin'],
  loadingBuilder: (_) => const Center(child: CircularProgressIndicator()),
  builder: (_) => const AdminDashboard(),
  fallbackBuilder: (_) => const AccessDeniedView(),
);

🔧 Example: Programmatic Async Evaluation #

final hasAccess = await GuardUtils.evaluateAsync(
  roleFuture: fetchUserRoles(),
  requiredRoles: const ['admin'],
);

📱 Example App #

A complete working example is available in:

example/

The example application demonstrates:

  • Guard
  • GuardNotifier
  • Reactive guard updates
  • Role changes at runtime
  • Permission changes at runtime
  • AccessGuard
  • RoleBasedView
  • CombinedGuard
  • PolicyGuard
  • AccessPolicy
  • AccessDecision
  • onDecision diagnostics
  • TimedAccessGuard
  • ScheduleGuard
  • DeviceTypeGuard
  • AsyncGuard
  • Developer override behavior

You can explore the example project to understand how the different guards can work together in a real Flutter application.


🧩 Common Use Cases #

Use Case Example
Admin-only screens requiredRoles: ['admin']
Guest-specific UI Display upgrade or login actions
Feature restrictions Hide paid features from free users
Auth state UI Show different actions based on access state
Nested permissions Combine moderator/admin roles
Permission-based actions Require permissions such as users.edit
Read-only vs edit access Conditionally render edit buttons or fields
Subscription tiers Control access for free, premium, or pro users
Combined logic Roles + permissions + runtime conditions
Reusable policies Share authorization rules with AccessPolicy
Access diagnostics Detect missing roles or permissions
Developer override Skip restrictions during development/testing
Time-based access Use TimedAccessGuard
Scheduled access Use ScheduleGuard
Business hours Enable UI using cron schedules
Promotions Show content only during campaign periods

📚 API Exports #

The main package export is:

import 'package:ui_guard/ui_guard.dart';

It includes the primary APIs required to use the package.

Core #

  • Guard
  • GuardNotifier
  • GuardConfig
  • RoleGuard
  • GuardUtils

Policies & Diagnostics #

  • AccessPolicy
  • AccessDecision

Widgets #

  • AccessGuard
  • RoleBasedView
  • CombinedGuard
  • PolicyGuard
  • TimedAccessGuard
  • ScheduleGuard
  • GuardListenableBuilder

🏗️ Example Architecture #

A common application structure could look like:

final guard = GuardNotifier();

void configureUserAccess() {
  guard.setUserRoles([
    'manager',
  ]);

  guard.setUserPermissions([
    'team.view',
    'team.edit',
  ]);
}

Then anywhere in your application:

AccessGuard(
  guard: guard,
  rebuildListenable: guard,
  requiredRoles: const ['manager'],
  builder: (_) => const ManagerDashboard(),
  fallbackBuilder: (_) => const AccessDeniedView(),
);

For reusable business rules:

const editTeamPolicy = AccessPolicy(
  name: 'edit_team',
  requiredRoles: ['manager'],
  requiredPermissions: ['team.edit'],
);

Use it wherever required:

PolicyGuard(
  guard: guard,
  rebuildListenable: guard,
  policy: editTeamPolicy,
  builder: (_) => const EditTeamButton(),
  fallbackBuilder: (_) => const SizedBox.shrink(),
);

This keeps your UI access logic clean, reusable, and easier to maintain as the application grows.


💬 Contributing #

Contributions are welcome! 🎉

Useful links:

To contribute:

  1. Fork the repository
  2. Create a new branch
  3. Make your changes
  4. Add or update tests where applicable
  5. Commit your changes
  6. Push your branch
  7. Submit a pull request

☕ Support My Work #

If you find ui_guard useful, consider supporting the project.

Buy Me a Coffee

Prefer mobile?

Scan the QR code below:

Buy Me a Coffee QR Code

Your support helps maintain and improve ui_guard. ❤️


👤 Maintainer #

MD. TANVIRUL ISLAM

GitHub: Tanvirul-swe


Made with ❤️ for the Flutter community.

11
likes
160
points
49
downloads

Documentation

API reference

Publisher

verified publisherfrozenlab.dev

Weekly Downloads

Easily manage role, permission, and condition-based access control in Flutter UIs — entirely in Dart.

Homepage
Repository (GitHub)
View/report issues

Topics

#flutter #plugin #user #role-based #access-control

License

MIT (license)

Dependencies

flutter

More

Packages that depend on ui_guard