Flag
Create customized boolean toggle fields (flags) that users can attach to any entity type, enabling features like bookmarks, favorites, spam reports, or any user-driven content markers.
flag
Install
composer require 'drupal/flag:^5.0'
Overview
The Flag module allows site administrators to define flexible boolean toggle fields (called 'flags') that can be attached to any Drupal entity type including nodes, comments, users, or custom entity types. Users with appropriate permissions can flag or unflag content, creating a rich ecosystem for user-driven content organization and interaction.
By default, flags operate on a per-user basis, meaning each authenticated user maintains their own set of flagged content. This enables personal features like bookmarks, favorites, or watch lists. Additionally, flags can be configured as 'global', where the flag state is shared across all users - useful for features like marking content as featured or offensive.
The module provides comprehensive Views integration for displaying and filtering flagged content, a plugin-based architecture for extensibility, event-driven hooks for custom reactions to flagging actions, and support for anonymous user flagging through session tracking. Flag also includes migration support from Drupal 6 and 7, making it easy to upgrade existing flag configurations.
Features
- Create unlimited custom flags with configurable labels, text, and behavior for any entity type (nodes, comments, users, custom entities)
- Per-user flagging (personal bookmarks, favorites) or global flagging (shared across all users for editorial features)
- Multiple link types: AJAX-powered instant toggle, confirmation forms, field entry forms with custom fields, or page reload
- Display flags as pseudo-fields in entity view modes, as checkboxes on entity edit forms, or in contextual menus
- Full Views integration with relationships, filters, sorts, and fields for building lists of flagged content
- Dynamic permissions system generating flag/unflag permissions for each flag, with optional owner-based permissions
- Event-driven architecture dispatching events when entities are flagged or unflagged for custom integrations
- Twig template functions (flagcount, flaglink) for rendering flag links and counts in custom templates
- Anonymous user flagging support with session-based tracking
- Action plugin integration for bulk flag/unflag operations via Views Bulk Operations
- Comprehensive token support for use in Rules, automated emails, and other token-aware modules
- Migration support from Drupal 6 and 7 Flag modules
Use Cases
Personal Bookmarks
Allow users to bookmark content for later reading. Create a per-user flag called 'bookmark' for nodes, use AJAX link type for instant feedback. Build a View filtered by the current user's bookmarks to create a 'My Bookmarks' page.
Content Favorites
Enable a favorites system where users can mark their favorite articles, products, or media. Use the flag count submodule to display popularity indicators showing how many users have favorited each item.
Spam/Abuse Reporting
Create a 'Report as spam' flag allowing users to flag inappropriate content. Configure with confirmation form link type to prevent accidental reports. Use Views to create an admin report showing flagged content sorted by flag count for moderation.
Editorial Featured Content
Use a global flag called 'featured' to mark content for homepage features. Since it's global, any editor can set it and the state is shared. Filter Views by this flag to dynamically populate featured content sections.
User Following System
Enable the flag_follower submodule or create a custom user flag for social following. Users can follow other users, and Views can display 'Followers' and 'Following' lists on user profiles.
Wishlist Functionality
For e-commerce sites, create a 'wishlist' flag for product content types. Use field entry link type to allow users to add notes or quantities when adding to wishlist. Display wishlist via Views with edit/remove capabilities.
Content Subscriptions
Create a 'subscribe' flag to allow users to subscribe to content for notifications. Hook into the flag.entity_flagged event to trigger email notifications when subscribed content is updated.
Voting/Rating Placeholder
While Flag itself is boolean, it can serve as the foundation for simple voting systems. Create 'upvote' and 'downvote' flags and use flag counts to calculate scores in Views or custom code.
Tips
- Use the flag_bookmark submodule as a reference implementation when creating your own flags
- For high-traffic sites, consider caching implications - contextual link display disables entity cache for users with flag access
- Add custom fields to flaggings via Field UI at /admin/structure/flags/manage/[flag]/fields for collecting additional data like notes or ratings
- Use the flagcount() and flaglink() Twig functions in custom templates for flexible flag display
- Subscribe to flag.entity_flagged and flag.entity_unflagged events for custom integrations like notifications or statistics
- Test anonymous flagging thoroughly as it relies on PHP session handling which varies by hosting environment
- Use template suggestions (flag--[flag_id].html.twig) to customize the appearance of specific flags
Technical Details
Admin Pages 7
/admin/structure/flags
Lists all configured flags on the site. From here administrators can view, edit, enable, disable, reset, or delete flags. The list shows the flag name, flag type (entity type it applies to), bundles it applies to, global status, and available operations.
/admin/structure/flags/add
First step of flag creation - select the entity type that this flag will be attached to. After selecting, continue to the full flag configuration form.
/admin/structure/flags/add/{entity_type}
Complete flag configuration form for creating a new flag. Configure all aspects of the flag including identification, scope, messages, access control, and display options.
/admin/structure/flags/manage/{flag}
Modify an existing flag's configuration. All settings from the add form are available for editing.
/admin/structure/flags/manage/{flag}/reset
Remove all flaggings for this flag. This permanently deletes all user flagging data associated with this flag.
/admin/structure/flags/manage/{flag}/enable
Re-enable a previously disabled flag, making it active on the site again.
/admin/structure/flags/manage/{flag}/disable
Temporarily disable a flag without deleting it. Disabled flags are not shown to users.
Permissions 8
Hooks 4
hook_flag_type_info_alter
Alter flag type plugin definitions provided by other modules. May be placed in a MODULE.flag.inc file.
hook_flag_options_alter
Alter a flag's default options. Use to add custom options that will be saved with the flag configuration.
hook_flag_link_type_info_alter
Alter action link type plugin definitions. May be placed in a MODULE.flag.inc file.
hook_flag_action_access
Perform custom access checks when a flag action is attempted. Return AccessResult objects to allow, deny, or remain neutral.
Troubleshooting 6
Verify the flag is enabled, the user has 'flag [flag_id]' permission, the flag applies to the content's bundle, and display options (show as field, show in links) are configured. Check Manage Display settings if using field display.
Ensure JavaScript is enabled, check for JS errors in browser console, verify the flag/flag.link_ajax library is loading. Try clearing Drupal cache and browser cache.
Anonymous flagging requires session-based tracking. Ensure PHP sessions are working correctly. Check that anonymous role has the flag permission. Note that page caching may interfere with anonymous flagging.
Flag counts are maintained by the FlagCountManager event subscriber. Clear caches and verify the event system is working. Check database table 'flag_counts' for data integrity.
Ensure you've added the flag relationship to your View and configured it to use the correct flag. Check that 'Include only flagged content' is set appropriately for your use case.
For Confirm Form or Field Entry link types, check the 'Form behavior' setting. Choose between 'New page', 'Dialog', or 'Modal dialog' based on your needs.
Security Notes 5
- The 'administer flags' and 'administer flaggings' permissions are marked as restricted access - grant only to trusted administrators
- Flag permissions are generated dynamically - review permissions after creating new flags to ensure appropriate access
- Anonymous flagging uses session IDs which can be manipulated - do not use for security-critical features
- CSRF protection is applied to all flag/unflag routes
- When using contextual links display, entity caching is disabled for users with flag access to prevent cached flag states from being shown