A tray is a popup panel that slides in from the edge of the screen, typically from the bottom, left, or right. It's commonly used in mobile interfaces for displaying action sheets, menus, or additional content panels.

Trays are ideal for presenting contextual actions, navigation options, or detailed content that doesn't require a full-screen modal. They maintain visual connection to the trigger element while providing a smooth slide-in animation.

The tray component supports configurable slide directions, optional drag handles for gesture-based dismissal, and customizable animation durations. Users can dismiss trays by tapping outside, using gestures, or through programmatic control.

Use trays for secondary actions, mobile-style navigation, or content that benefits from the edge-anchored presentation. They work particularly well on touch interfaces where gesture-based interaction is natural.

Anatomy

Tray Examples:

<appui:Tray position="Bottom" showHandle="true" size="M" />

Bottom tray with drag handle (mobile action sheet style)

Different Positions:

<appui:Tray position="Bottom" showHandle="true" size="M" />

Bottom tray for mobile actions

<appui:Tray position="Left" showHandle="false" size="M" />

Left side navigation menu

<appui:Tray position="Right" showHandle="true" size="M" />

Right side filter panel

<appui:Tray position="Top" showHandle="false" size="M" />

Top notification tray

Handle Visibility:

<appui:Tray position="Bottom" showHandle="true" size="M" />

With drag handle for gesture control

<appui:Tray position="Bottom" showHandle="false" size="M" />

Without handle for clean appearance

Transition Speeds:

<appui:Tray position="Bottom" transitionDurationMs="150" size="M" />

Fast animation (150ms)

<appui:Tray position="Bottom" transitionDurationMs="300" size="M" />

Standard animation (300ms)

<appui:Tray position="Bottom" transitionDurationMs="500" size="M" />

Slow animation (500ms)

Disabled State:

<appui:Tray position="Bottom" showHandle="true" enabled="false" size="M" />

Non-interactive tray overlay

Examples

Bottom action sheet. Creating a mobile-style action sheet that slides from the bottom.

var actionButton = new Button { title = "More Actions" };
// Create action sheet content
var actionSheet = new VisualElement();
actionSheet.AddToClassList("action-sheet");
var header = new VisualElement();
header.Add(new Text("Choose an action") );
actionSheet.Add(header);
var actions = new VisualElement();
actions.Add(new MenuItem { label = "Share", icon = "share" });
actions.Add(new MenuItem { label = "Edit", icon = "edit" });
actions.Add(new MenuItem { label = "Delete", icon = "trash", variant = MenuVariant.Destructive });
actionSheet.Add(actions);
var tray = Tray.Build(rootElement, actionSheet)
.SetPosition(TrayPosition.Bottom)
.SetHandleVisible(true)
.SetTransitionDuration(300);
actionButton.clicked += () => tray.Show();
content.Add(actionButton);

Side navigation tray. Creating a navigation menu that slides from the side.

var menuButton = new IconButton { icon = "menu" };
// Create navigation menu content
var navMenu = new VisualElement();
navMenu.AddToClassList("side-navigation");
var header = new VisualElement();
header.Add(new Avatar );
header.Add(new Text("John Doe"));
navMenu.Add(header);
var menuItems = new VisualElement();
menuItems.Add(new MenuItem { label = "Dashboard", icon = "dashboard", selected = true });
menuItems.Add(new MenuItem { label = "Projects", icon = "folder" });
menuItems.Add(new MenuItem { label = "Settings", icon = "settings" });
menuItems.Add(new Divider );
menuItems.Add(new MenuItem { label = "Logout", icon = "logout" });
navMenu.Add(menuItems);
var sideTray = Tray.Build(rootElement, navMenu)
.SetPosition(TrayPosition.Left)
.SetHandleVisible(false)
.SetTransitionDuration(250);
menuButton.clicked += () => sideTray.Show();
appBar.leadingContainer.Add(menuButton);

Right-side filter panel. Creating a filter/options panel that slides from the right.

var filterButton = new Button { title = "Filters", trailingIcon = "filter" };
// Create filter panel content
var filterPanel = new VisualElement();
filterPanel.AddToClassList("filter-panel");
filterPanel.Add(new Heading );
var categoryFilter = new VisualElement();
categoryFilter.Add(new Text("Category"));
var categoryDropdown = new Dropdown();
categoryDropdown.choices.AddRange(new[] { "All", "Documents", "Images", "Videos" });
categoryFilter.Add(categoryDropdown);
filterPanel.Add(categoryFilter);
var dateFilter = new VisualElement();
dateFilter.Add(new Text("Date Range"));
dateFilter.Add(new DateRangeField());
filterPanel.Add(dateFilter);
var buttons = new VisualElement();
buttons.Add(new Button { title = "Reset", quiet = true });
buttons.Add(new Button { title = "Apply", variant = ButtonVariant.Accent });
filterPanel.Add(buttons);
var filterTray = Tray.Build(rootElement, filterPanel)
.SetPosition(TrayPosition.Right)
.SetHandleVisible(true)
.SetTransitionDuration(200);
filterButton.clicked += () => filterTray.Show();

Methods

AnimateViewIn()

Start the animation for this popup.

Declaration

protected override void AnimateViewIn()

Overrides

Popup.AnimateViewIn()

AnimateViewOut(DismissType)

Start the hide animation for this popup.

Declaration

protected override void AnimateViewOut(DismissType reason)

Parameters

Type	Name	Description
DismissType	reason	The reason why the popup should be dismissed.

Overrides

Popup.AnimateViewOut(DismissType)

Build(VisualElement, VisualElement)

Build a new Tray component.

Declaration

public static Tray Build(VisualElement referenceView, VisualElement content)

Parameters

Type	Name	Description
VisualElement	referenceView	An arbitrary UI element inside the UI panel.
VisualElement	content	The content to display inside this Tray.

Returns

Type	Description
Tray	The Tray instance.

Exceptions

Type	Condition
ArgumentNullException	If `referenceView` is null.

GetFocusableElement()

Returns the element that will be focused when the view will become visible.

The default value is `null`.

Declaration

protected override VisualElement GetFocusableElement()

Returns

Type	Description
VisualElement	The element that will be focused when the view will become visible.

Overrides

Popup.GetFocusableElement()

HideView(DismissType)

Called when it is time to hide the popup.

Declaration

protected override void HideView(DismissType reason)

Parameters

Type	Name	Description
DismissType	reason	The reason why the popup should be dismissed.

Overrides

Popup.HideView(DismissType)

InvokeShownEventHandlers()

Called when the popup has become visible. This method will invoke any handlers attached to the shown event.

Declaration

protected override void InvokeShownEventHandlers()

Overrides

Popup<Tray>.InvokeShownEventHandlers()

OnLayoutReadyToAnimateIn()

Called when the layout is ready to be animated in.

Declaration

protected override void OnLayoutReadyToAnimateIn()

Overrides

Popup.OnLayoutReadyToAnimateIn()

SetHandleVisible(bool)

Set the handle visibility.

Declaration

public Tray SetHandleVisible(bool value)

Parameters

Type	Name	Description
bool	value	The handle visibility.

Returns

Type	Description
Tray	The Tray instance.

SetPosition(TrayPosition)

Build a new Tray component.

Declaration

public Tray SetPosition(TrayPosition position)

Parameters

Type	Name	Description
TrayPosition	position	The position of the tray.

Returns

Type	Description
Tray	The Tray instance.

SetTransitionDuration(int)

Set the transition duration.

Declaration

public Tray SetTransitionDuration(int durationMs)

Parameters

Type	Name	Description
int	durationMs	The transition duration in milliseconds.

Returns

Type	Description
Tray	The Tray instance.

ShouldAnimate()

Implement this method to know if the popup should call AnimateViewIn() and AnimateViewOut(DismissType) methods or not.

Declaration

protected override bool ShouldAnimate()

Returns

Type	Description
bool	`True` if you want to animate the popup, `False` otherwise.

Overrides

Popup.ShouldAnimate()

ShouldDismiss(DismissType)

Dismiss the Popup.

Declaration

protected override bool ShouldDismiss(DismissType reason)

Parameters

Type	Name	Description
DismissType	reason	Why the element has been dismissed.

Returns

Type	Description
bool	True if the element has been dismissed.

Overrides

Popup.ShouldDismiss(DismissType)