xamarin
[Spec] Badge support for Shell
Summary
There are requests for badge support for classic tabs and there are also some libraries out there which kinda support that. With shell it's not possible to use this libraries without touching / replacing too much of the shell internals so it would be great if shell supports this scenario out of the box. I couldn't find anything related in shell spec, that's why I'm proposing it here.
API Changes
Badges should be supported on all shell navigation patterns, which are
- Flyout menu items
- Bottom tabs
- Top tabs
I propose the following properties for first iteration of badge support:
Primary properties
BaseShellItem (bindable properties)
BadgeText: string to set the number (or something else) of notification-like itemsBadgeMoreText: string to set the number (or something else) of the aggregated more tabBadgeTextColor: Foreground color of badge textBadgeUnselectedTextColor: Foreground color of badge text if underlying navigation item is in unselected stateBadgeEffectiveTextColor (readonly): IfBadgeUnselectedTextColoris unset,BadgeTextColorwill be returned. Otherwise it will returnBadgeTextColorif the underlying navigation item is in selected state orBadgeUnselectedTextColorif in unselected state.BadgeColor: background color of badgeBadgeUnselectedColor: background color of badge if navigation item is in unselected stateBadgeEffectiveColor (readonly): IfBadgeUnselectedColoris unset,BadgeColorwill be returned. Otherwise it will returnBadgeColorif the underlying navigation item is in selected state orBadgeUnselectedColorif in unselected state.
Future implementations / considerations
- Add font image support (might also work for "little dot mode")
- CSS Styling
- Inheritance of styling related properties
- Additional More properties (TextColor, UnselectedTextColor, Color, UnselectedColor, ...)
Bottom tabs use the concept of the More tab if there are more than 5 items. All items with index >= 5 will be "hidden" by this more tab and handled by a platform specific context menu.
One use case would be the transformation of the underlying items hidden by this more tab. For example Item 5 (Messages) has "1" new item and Item 6 (Notifications) has "2" new items, so you could show "3" in the more tab, but the user would not how how this is split between the aggregated items.
We could think of modifying the text (e.g. for the example above "Messages (1)" and "Notifications (6)"). I'm proposing this because adding a badge to the underlying platform specific context menu could be too much work / impossible for a specific platform. Modifying the title value should definitely work though and we would see at least something.
Internal implementation
Android
Material components will support badges out of the box, which when I understood it correctly can be used when AndroidX is supported by Xamarin. In the meantime we have to supply a custom implementation like this for badges.
Flyout
Flyout menu is created by the ShellFlyoutTemplatedContentRenderer in combination with ShellFlyoutRecyclerAdapter. The data template is based on forms controls, so we just might use a Frame here for the default template. For custom templates the user has to provide the necessary controls and bind color, text, etc..
Bottom tabs
ShellItemRenderer uses BottomNavigationView, which can be used to retrieve the underlying BottomNavigationItemView items and inject the badge view.
The more tab uses a BottomSheetDialog.
Top tabs
ShellSectionRenderer uses TabLayout, which can be used to retrieve the underlaying TabView items and inject the badge view.
iOS
Flyout
Flyout menu is created by the ShellTableViewController in combination with ShellTableViewSource. The data template is based on forms controls, so we just might use a Frame here for the default template. For custom templates the user has to provide the necessary controls and bind color, text, etc..
Bottom tabs
ShellItemRenderer uses UITabBarController which can use the UITabBarItem to specify native Badge properties.
The more tab uses the default implementation of the MoreNavigationController of UITabBarController.
Top tabs
ShellSectionRootRenderer uses a UICollectionView, so you would have to modify ShellSectionHeaderCell and add a custom badge view (something like this).
Screenshots
TODO: Add them here
Feedback welcome.
I have started implementation for bottom tabs support (see fork), because this will cover most needs and is the easiest to implement.
How should I proceed? Should I go for a PR? Do you want to refine specification or implementation details?
Android
iOS
@Dresel can you create a draft PR against your fork and then we can check it out?
Badge support shouldn't be limited to only Tabs (top or bottom) - it should also be supported in the FlyoutMenu itself so the badges can be seen when the flyout opens and users don't need to navigate into each page to see the badges.
Badge support shouldn't be limited to only Tabs (top or bottom) - it should also be supported in the FlyoutMenu itself so the badges can be seen when the flyout opens and users don't need to navigate into each page to see the badges.
Yes, it's on my (extended) list, might look similar to
Since Flyout Items are rendered with forms controls and can use custom templates, it's (from an implementations perspective) different though. I will update the spec according to that soon.
Can we please have this for non Shell too? I am thinking that it should be first implemented in the non Shell (classic) and then surfaced in Shell.
If we start having having feature discrepancies between Shell and non-Shell that doesn’t sound good to me. I am referring to only features like this one, obviously not everything can or should be in non Shell, that’s the reason why Shell exists.
Can we please have this for non Shell too? I am thinking that it should be first implemented in the non Shell (classic) and then surfaced in Shell.
If we start having having feature discrepancies between Shell and non-Shell that doesn’t sound good to me. I am referring to only features like this one, obviously not everything can or should be in non Shell, that’s the reason why Shell exists.
What's wrong with packages like xamarin-forms-tab-badge? Problem with shell is that it's not possible to use this libraries without touching / replacing too much of the shell internals, that's why I was proposing this in the first place.
My suggestion is not related to that package, it might be a great package. I was only suggesting a way I think it's best to handle this, which is to give this new feature to non-Shell apps too. I just wanted to share my feedback, your proposal is great.
Yep, for our app to be able to continue to use the new Shell, this is a must! Thanks, and waiting anxiously!
Yep, for our app to be able to continue to use the new Shell, this is a must! Thanks, and waiting anxiously!
Also for our app! This is highly requested from the business side
when will the badge for shell appear in xamarin forms? Can you show an example of a renderer for Tab (ShellSection) with badge?
I'm currently waiting for review / feedback from the XF team, I cannot tell you when this will be ready.
Can you show an example of a renderer for Tab (ShellSection) with badge?
If you want you can build the XF repo and play with the Control Gallery sample or check the PR sources.
@Dresel do you have an ETA when badge support within toolbar and flyout menu will be available? We're released a Xamarin based app and user engagement is being impacted by the lack of badges. In-app badges are essential for all modern apps and I'm surprised that this feature is not getting prioritized on the Xamarin team. Thanks and looking forward to your feedback.
@Dresel do you have an ETA when badge support within toolbar and flyout menu will be available? We're released a Xamarin based app and user engagement is being impacted by the lack of badges. In-app badges are essential for all modern apps and I'm surprised that this feature is not getting prioritized on the Xamarin team. Thanks and looking forward to your feedback.
PR is ready for review - hopefully soon 👍
When is this going to be released?
I'm currently waiting for review. I don't know how work items are prioritized, maybe @samhouts can tell you more.
I'm pretty sure you have a team of testers ready to check it out, myself included.
When is this going to be released?
I'm currently waiting for review. I don't know how work items are prioritized, maybe @samhouts can tell you more.
@samhouts will this be included anytime soon? Been waiting on this for awhile since switching to AppShell! It's pretty much expected in apps to have a red badge on a tab icon for notifications....
We're still reviewing the PR. We hope to have it ready soon! Thanks for your patience!
Hello @samhouts really this is an urgent in our software , I hope it will be applied so soon Thank you
Hello. +1 assigning to the priority of this feature. It's a "must-have" thing for Xamarin.Forms development with the help of Shell.
What does "ready soon" mean? I don't know why this takes so long, it's open for more than a year now and a very basic feature. I hope it will be really ready soon ...
