Widgets that make role, permission, and condition-based UI control simple, scalable, and secure.
Built entirely in Dart to help you build smarter, access-aware Flutter apps.

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

🔐 Why use ui_guard?

In many apps, you need to control access to certain parts of your UI:

• Show settings only to admins
• Render upgrade buttons for guests
• Show/hide widgets based on subscription level

ui_guard lets you do this easily and declaratively — using only Dart.

---

✨ Features

• ✅ Guard widgets or entire screens based on roles
• 🧩 Combine roles, permissions, and runtime conditions
• 🧪 Developer override mode for UI testing
• 🔄 Easily update roles at runtime
• 📦 Pure Dart — no platform dependencies
• ♻️ Works with any state management

---

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  ui_guard: ^1.0.0

🧠 Core API

A simple class to store and manage the current user's roles.

🔹 Guard

A simple class to store and manage the current user's roles.

final guard = Guard();
guard.setUserRoles(['admin']); // Set roles for current user

print(guard.currentRoles); // ['admin']

🔹 AccessGuard

Renders content conditionally based on required roles.

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

🔹 RoleBasedView

Use when you want to show/hide a single widget inline.

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

🔹 RoleGuard

Utility class with common access logic:

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

🧪 Developer Override Mode

Bypass all restrictions during development or testing:

class GuardConfig {
  static bool developerOverrideEnabled = true; // Use in dev only
}

🧮 Combined Access Conditions

Create advanced rules using roles, permissions, and runtime checks:

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

⏱️ Timed Access Control

Use TimedAccessGuard to control UI visibility based on time. Ideal for:

• 🎁 Limited-time offers & flash sales
• 🧪 Beta or trial feature access
• 🔧 Maintenance or downtime notices
• 📅 Event-specific content
• 🛍️ Daily/weekly deals
• 📢 Time-based announcements
• 🏢 Business-hour-only features

TimedAccessGuard(
  start: DateTime(2025, 7, 18, 9),
  end: DateTime(2025, 7, 18, 13),
  checkInterval: Duration(seconds: 1),
  onTimeUpdate: (remaining) {
    debugPrint("⏱️ Time left: ${remaining.inSeconds}s");
  },
  builder: (_) => PromoBanner(), // Active content
  fallbackBuilder: (_) => SizedBox.shrink(), // Hidden or fallback
),

📱 Example App

Explore the full working example in the /example directory.

🧩 Use Cases

Here are some common scenarios where ui_guard is useful:

Use Case	Example
Admin-only screens	requiredRoles: ['admin']
Feature restrictions	Hide paid features from free users
Auth state UI	Show "Login" or "Logout" buttons based on roles
Nested permissions	Show moderator tools for ['moderator', 'admin'] roles
Read-only vs edit access	Conditionally render buttons or fields
Subscription tiers	Control access with ['free', 'premium', 'pro'] roles
Combined logic	Use roles + permissions + runtime conditions
Developer override	Skip restrictions in development or test
Time-based access	Display banners or UI only within a defined time range TimedAccessGuard

💬 Contributing

Contributions are welcome!

• 🌐 GitHub
• 🐛 Issues

To contribute:

1. Fork the repository
2. Create a new branch
3. Commit your changes
4. Submit a pull request

🛠️ Dart SDK Version

This package requires Dart SDK version >=2.14.

Please ensure your Flutter and Dart versions meet this requirement.

---

☕ Support My Work

If you find ui_guard helpful, consider supporting me!

Prefer mobile? Scan the QR code below to support me directly:

👤 Maintainers

• MD. TANVIRUL ISLAM