NE.Standard

Menu

A list of navigation entries, vertical or horizontal, that can collapse to icons alone.

MenuComponent · type key standard.menu · Navigation · property blocks: IOrientationComponent, ISpacingComponent, ICollapsibleComponent, ISelectionStyleComponent, ISurfaceStyleComponent, IEmptyStateComponent, IAccessibleNameComponent

Surface names the popup's fill — the context menu, split button list, or sub-entry flyout — and a sidebar's or rail's own ground. One collection carries entries, captions, rules, checks and selects via IMenuItemModel.Kind; checks and selects write back to the bound item, so they need a bound collection, not entries set once. Folded to its icons, an entry's title is its tooltip unless the entry has a tooltip of its own, and its badge stands on the icon's corner. Unset, Spacing is the stylesheet's: a list's entries stand the list gap apart, so a chosen ground and the pointer's read as two, while a bar's and a rail's stand edge to edge, their grounds square slices with no rounded hover to set apart.

new MenuComponent("menu")

Properties

PropertyTypeDefaultBindingDescription
Own
Display
SetDisplay
UIResponsive<UIMenuDisplay>?List—How the entries are laid out, per breakpoint: rows of icon and title, or a rail of icons each over a one-line label.
Render-time only. One menu may be a rail on one width and a list on another (SetDisplay(UIMenuDisplay.Rail, xl: UIMenuDisplay.List)): the browser draws the shape of the width it stands at. Where a view's left side is a drawer, the base tier alone says whether a menu there is the phone's bottom bar or a rail drawn as a list; a sm tier never does. A rail has nothing to fold, so it ignores Expanded and draws no collapse toggle; the fold is kept for the widths it is a list on. An entry's label cut short shows whole as its tooltip unless the entry has one of its own; a badge stands on the icon's corner, an empty BadgeTitle as a dot; the current entry wears its icon filled. The rail's ground is MenuComponent.Surface's. A rail takes no search (MenuComponent.SetSearch): its groups fly out, so a match among their entries would not show; a search typed on a list is let go of where it turns into a rail. A rail that is the whole of a view's left side is the page's bottom navigation bar on a phone rather than a drawer (UIMenuDisplay.Rail says when): its entries share the width down to a press's width each (MenuComponent.Size says which) and then scroll sideways, the current one marked on its top edge, over the bar's hairline — or, where the view turns UIViewOptions.RailBottomBar off, it is that side's drawer drawn as a list. A rail's entries stand edge to edge, as square slices of it.
DrawerPin
SetDrawerPin
bool?false—Whether a sidebar menu that is a side's drawer offers to pin it: a pin at the end of its top row, after the switch and the search, which keeps the side in its column from the extra-large breakpoint up until it is pressed again.
Render-time only, and a list's alone: a rail is no drawer's head. Shown only where pinning means something — from the extra-large breakpoint up, where the side is a drawer (UIViewOptions.SideDrawers) or pinned. The pin is kept in the browser under the first authored id in the side (the menu's, where nothing around it has one); a side with no menu is pinned by a button of the page's own (ButtonComponent.PinsDrawer).
Size
SetSize
UIResponsive<UISize>?Medium—How much room a rail takes — its column, its glyphs and labels — and the bottom bar it becomes on a phone, optionally per breakpoint.
Render-time only, and a rail's alone (UIMenuDisplay.Rail): a list menu's rows keep their size. Large is a 72 px column of 24 px glyphs over caption-size labels; Medium, the default, 60 px of 20 px glyphs over overline-size labels; Small 48 px of 20 px glyphs alone, each label kept as the entry's name and shown as its tooltip. On the bar an entry is squeezed no narrower than 64, 56 or 48 px.
Nested
SetNested
bool?false—Whether this menu is another entry's sub-entries: it folds and flies out with that entry.
Render-time only: a nested list is built as its entry's block.
ShowSearchbool?false—Whether the menu carries a search beside its switch, which narrows the entries in the browser as it is typed into.
Render-time only: MenuComponent.SetSearch puts the field in and turns this on.
Orientation
SetOrientation · BindOrientation
UIResponsive<UIOrientation>?Verticalone-wayWhich way the component runs, optionally per breakpoint (a column on a phone, a row wider up); vertical unless the component says otherwise.
Spacing
SetSpacing · BindSpacing
UIResponsive<double>?nullone-wayThe gap between the component's children or entries, optionally overridden per breakpoint.
Unset, the stylesheet's own gap for the component applies, which may depend on its shape.
Expanded
SetExpanded · BindExpanded
bool?trueone-wayWhether the component is unfolded (the authored start, or a bound value); the viewer's own fold stays client-side and may later disagree.
An expander's is two-way, the viewer's fold written back; a collapsible's fold stays the viewer's, client-side.
Side
SetSide
UISide?UISide.Left—The edge the component sits on and folds toward, which decides whether width or height collapses.
ShowCollapseToggle
SetShowCollapseToggle
bool?false—Whether the component draws its own switch for ICollapsibleComponent.Expanded.
SelectionStyle
SetSelectionStyle · BindSelectionStyle
UISelectionStyle?nullone-wayWhat a chosen item looks like. Unset, and every unset part of it, is the control's own default.
Surface
SetSurface · BindSurface
UISurfaceStyle?nullone-wayWhat the component is made of.
ShowEmptyTemplate
SetShowEmptyTemplate · BindShowEmptyTemplate
bool?trueone-wayWhether the empty template is drawn while the host holds nothing; on by default.
AccessibleName
SetAccessibleName · BindAccessibleName
UIPhrasenullone-wayThe name a screen reader announces in place of the visible words; unset, the control is named by what it shows. The set is a wrapper's hand (a labelled control is named by its label), an author's own words said at the component. translatable
From ItemsComponentBase
Items
SetItems · BindItems
IReadOnlyList<IMenuItemModel>nullone-wayThe component items.
ItemsView
BindItemsView
UIItemsViewnullone-wayFiltering and sorting rules applied to the items collection.
Query
SetQuery · BindQuery
UIItemsQuerynulltwo-wayThe terms the viewer set after the view compiled (a header's sort, a filter row), applied beside the authored rules; two-way bound, so a windowed source is asked with them.
ItemReadsUIItemReadsnull—What the page reads off the rows beyond what the templates, rules and keys read — a client engine reading items raw — or null for nothing more; a row carries only what is read (UIItemReads.Whole sends it whole).
From TemplatedComponentBase
TemplateKeyProperty
SetTemplateKeyProperty
string"Kind"—The name of the item field whose value selects a named template variant.
Render-time only: the renderer and the runtime read it off the compiled state to pick a variant, so a binding would change nothing.
FallbackTemplateKey
SetFallbackTemplateKey
stringnull—The fallback template key used when ITemplatedComponent.TemplateKeyProperty does not resolve to a template.

Events

OnClickableItemTemplates(Action<IVisualComponent> register)
Writes a click on the entry and check templates, now and whenever either is set again; captions and rules take no click, and a select's own click only opens its choices.
OnExpand(string command)
Registers a command to invoke when the component is expanded.
OnExpand(string command, params KeyValuePair<string, UIActionArgument>[] arguments)
Registers a command with bound arguments to invoke when the component is expanded.
OnExpandLiteral(string command, params KeyValuePair<string, object>[] arguments)
Registers a command with literal arguments to invoke when the component is expanded.
OnCollapse(string command)
Registers a command to invoke when the component is collapsed.
OnCollapse(string command, params KeyValuePair<string, UIActionArgument>[] arguments)
Registers a command with bound arguments to invoke when the component is collapsed.
OnCollapseLiteral(string command, params KeyValuePair<string, object>[] arguments)
Registers a command with literal arguments to invoke when the component is collapsed.
OnItemClick(string command)
Registers a click command invoked when an item is clicked.
OnItemClick(string command, params KeyValuePair<string, UIActionArgument>[] arguments)
Registers a click command invoked when an item is clicked, with UI action arguments.
OnItemClick(ClientEffect effect)
Runs a client effect when any item is clicked — a menu's or a split button's entries inserting their own key with InsertTextEffect.CurrentItemKey — with no round trip.
OnItemClick(string key, ClientEffect effect)
Runs a client effect when the item whose key is key is clicked — a menu's Copy, a context menu's or an action bar's entry, a split button's — with no round trip; the other items keep the command OnItemClick gave them.
The key is the item's, so a bound list's entries take it as a declared one's do; an effect aimed at the row the menu stands in (a message's text) finds it there. Only an effect an interaction may run is taken. Given twice for one key, both run.
OnItemClickLiteral(string command, params KeyValuePair<string, object>[] arguments)
Registers a click command invoked when an item is clicked, with literal argument values.
OnItemClickWithItem(string command, string argumentName = "item")
Registers a click command that passes the clicked item as an argument.
OnItemClickWithItemKey(string command, string argumentName = "id")
Registers a click command that passes the clicked item's key as an argument.
OnItemClickWith(string command, string argumentName, UIActionArgumentKind argumentKind)
Registers a click command with an argument derived from the specified argumentKind.

Methods

SetToggleContent(IVisualComponent content)
Puts content beside the menu's switch, in one row with it — a title, a button of the menu's own — seen only while the menu is open. MenuComponent.SetSearch puts a search there.
SetSearch(UIPhrase? placeholder = null)
Puts a search beside the menu's switch, the field TextInputComponent.SetSearch makes, Filled and small: what is typed narrows the entries in the browser by the words they show.
A group stays, open, while one of its sub-entries matches, and a caption while an entry under it does. A search that leaves nothing shows the menu's empty template, as a select's does — the default one's "Nothing to show." unless the author set one.
SetSubmenuDepth(int depth)
Sets how many levels of nested sub-entries the menu compiles templates for (MenuComponent.DefaultSubmenuDepth by default, up to MenuComponent.MaxSubmenuDepth); entries set through SetItems raise this to their own depth automatically.
SetTemplate(IButtonComponent visualTemplate)
Sets the item template.
AddTemplateVariant(string key, IButtonComponent visualTemplate)
Adds or replaces a named template variant.
AddItemReads(params Expression<Func<TRow, object>>[] paths)
Names item paths the page reads off the rows beyond what the templates bind, so each row carries them.
AddItemReads(params string[] paths)
Names item paths the page reads off the rows beyond what the templates bind (a client engine reading rows.itemOf), so each row carries them; dotted, as a binding's path.
ReadsWholeItems()
Sends every row's item whole: something on the page reads it raw, past what the compile can see.
AddItem(IMenuItemModel item)
Adds an item to the component.
AddItems(IEnumerable<IMenuItemModel> items)
Adds items to the component.
FilterBy(UIProperty source, Expression<Func<TRow, object>> itemProperty, UIComparisonOperator operator = UIComparisonOperator.LikeIgnoreCase, UIComparisonOperator activeOperator = UIComparisonOperator.Required, object? activeValue = null)
Adds a filter controlled by a local component property.
FilterBy(UIProperty source, string itemProperty, UIComparisonOperator operator = UIComparisonOperator.LikeIgnoreCase, UIComparisonOperator activeOperator = UIComparisonOperator.Required, object? activeValue = null)
Adds a filter controlled by a local component property.
Defaults to a case-insensitive substring match; pass the operator explicitly where case matters.
FilterBy(string sourceComponentId, UIProperty source, Expression<Func<TRow, object>> itemProperty, UIComparisonOperator operator = UIComparisonOperator.LikeIgnoreCase, UIComparisonOperator activeOperator = UIComparisonOperator.Required, object? activeValue = null)
Adds a filter controlled by another component property.
FilterBy(string sourceComponentId, UIProperty source, string itemProperty, UIComparisonOperator operator = UIComparisonOperator.LikeIgnoreCase, UIComparisonOperator activeOperator = UIComparisonOperator.Required, object? activeValue = null)
Adds a filter controlled by another component property.
FilterBy(UIPropertyReference source, Expression<Func<TRow, object>> itemProperty, UIComparisonOperator operator = UIComparisonOperator.LikeIgnoreCase, UIComparisonOperator activeOperator = UIComparisonOperator.Required, object? activeValue = null)
Adds a filter controlled by a property reference.
FilterBy(UIPropertyReference source, string itemProperty, UIComparisonOperator operator = UIComparisonOperator.LikeIgnoreCase, UIComparisonOperator activeOperator = UIComparisonOperator.Required, object? activeValue = null)
Adds a filter controlled by a property reference.
FilterBy(Expression<Func<TRow, object>> itemProperty, UIComparisonOperator operator = UIComparisonOperator.LikeIgnoreCase, object? value = null)
Adds an unconditionally active filter with no source, comparing against a constant value.
FilterBy(string itemProperty, UIComparisonOperator operator = UIComparisonOperator.LikeIgnoreCase, object? value = null)
Adds an unconditionally active filter with no source, comparing against a constant value.
SortBy(UIProperty source, Expression<Func<TRow, object>> itemProperty, UIItemsSortDirection direction = UIItemsSortDirection.Ascending, UIComparisonOperator activeOperator = UIComparisonOperator.Equal, object? activeValue = null, int priority = 0)
Adds a sort rule controlled by a local component property.
SortBy(UIProperty source, string itemProperty, UIItemsSortDirection direction = UIItemsSortDirection.Ascending, UIComparisonOperator activeOperator = UIComparisonOperator.Equal, object? activeValue = null, int priority = 0)
Adds a sort rule controlled by a local component property.
SortBy(string sourceComponentId, UIProperty source, Expression<Func<TRow, object>> itemProperty, UIItemsSortDirection direction = UIItemsSortDirection.Ascending, UIComparisonOperator activeOperator = UIComparisonOperator.Equal, object? activeValue = null, int priority = 0)
Adds a sort rule controlled by another component property.
SortBy(string sourceComponentId, UIProperty source, string itemProperty, UIItemsSortDirection direction = UIItemsSortDirection.Ascending, UIComparisonOperator activeOperator = UIComparisonOperator.Equal, object? activeValue = null, int priority = 0)
Adds a sort rule controlled by another component property.
SortBy(UIPropertyReference source, Expression<Func<TRow, object>> itemProperty, UIItemsSortDirection direction = UIItemsSortDirection.Ascending, UIComparisonOperator activeOperator = UIComparisonOperator.Equal, object? activeValue = null, int priority = 0)
Adds a sort rule controlled by a property reference.
SortBy(UIPropertyReference source, string itemProperty, UIItemsSortDirection direction = UIItemsSortDirection.Ascending, UIComparisonOperator activeOperator = UIComparisonOperator.Equal, object? activeValue = null, int priority = 0)
Adds a sort rule controlled by a property reference.
SortBy(Expression<Func<TRow, object>> itemProperty, UIItemsSortDirection direction = UIItemsSortDirection.Ascending, int priority = 0)
Adds an unconditionally active sort rule with no source.
SortBy(string itemProperty, UIItemsSortDirection direction = UIItemsSortDirection.Ascending, int priority = 0)
Adds an unconditionally active sort rule with no source.
SetEmptyTemplate(IVisualComponent visualTemplate)
Sets the template used when there are no items or no content.
ConfigureDefaultEmptyTemplate(Action<DefaultEmptyTemplate> configure)
Configures the built-in default empty template, putting it in where the host has none, and throwing if a different template has been set.
On demand on every host, so a menu or a key-value list that starts with none (an empty context menu says nothing) and a list that starts with one are worded alike.
SetCollapsed()
Sets IExpandableComponent.Expanded to false.
ConfigureTemplate(TTemplate? current, Action<TTemplate> configure, string what)
Configures current when it is a TTemplate, throwing when a different one was set.
Common properties (23) — layout, visibility, theme, and the rest every component shares
PropertyTypeDefaultBindingDescription
Visibility
SetVisibility · BindVisibility
UIResponsive<UIVisibility>?Visibleone-wayWhat the component does with the room it was given, optionally overridden per breakpoint (e.g. collapsed from a given width up).
Hidden at every width — by a static value or a controller binding — the server refuses a command or a value the component or anything inside it sends. That is a guard against a stale or forged page, not the permission itself: an interaction that hides it (HiddenWhen) lives on the client alone, so who may act belongs in the command or the setter.
Enabled
SetEnabled · BindEnabled
bool?trueone-wayWhether the component responds to input; false dims it and marks it, and its subtree, inert.
False by a static value or a controller binding, the server refuses a command or a value the component or anything inside it sends. That is a guard against a stale or forged page, not the permission itself: an interaction that disables it (EnabledWhen) lives on the client alone, so who may act belongs in the command or the setter.
Theme
SetTheme · BindTheme
UIThemeMode?nullone-wayThe theme mode forced on this component's subtree, or null to inherit the ambient theme.
HorizontalAlignment
SetHorizontalAlignment · BindHorizontalAlignment
UIResponsive<UIAlignment>?Stretchone-wayWhere the component sits within its grid cell along the horizontal axis, optionally overridden per breakpoint.
VerticalAlignment
SetVerticalAlignment · BindVerticalAlignment
UIResponsive<UIAlignment>?Stretchone-wayWhere the component sits within its grid cell along the vertical axis, optionally overridden per breakpoint.
Width
SetWidth · BindWidth
UIResponsive<UILayoutLength>?nullone-wayThe component width, optionally overridden per breakpoint.
MinWidth
SetMinWidth · BindMinWidth
UIResponsive<UILayoutLength>?nullone-wayThe component minimum width, optionally overridden per breakpoint.
MaxWidth
SetMaxWidth · BindMaxWidth
UIResponsive<UILayoutLength>?nullone-wayThe component maximum width, optionally overridden per breakpoint.
Height
SetHeight · BindHeight
UIResponsive<UILayoutLength>?nullone-wayThe component height, optionally overridden per breakpoint.
MinHeight
SetMinHeight · BindMinHeight
UIResponsive<UILayoutLength>?nullone-wayThe component minimum height, optionally overridden per breakpoint.
MaxHeight
SetMaxHeight · BindMaxHeight
UIResponsive<UILayoutLength>?nullone-wayThe component maximum height, optionally overridden per breakpoint.
ZIndex
SetZIndex · BindZIndex
int?0one-wayThe stacking order within the visual tree.
Margin
SetMargin · BindMargin
UIResponsive<UIThickness>?nullone-wayThe outer spacing around the component, optionally overridden per breakpoint.
Placement
SetPlacement · BindPlacement
UIResponsive<UIGridPlacement>?nullone-wayThe grid placement, optionally overridden per breakpoint.
AlignWithFieldBoxes
SetAlignWithFieldBoxes
UIResponsive<UIFieldBoxAlignment>?null—Whether the component stands level with the boxes of captioned fields beside it — a caption line down, centred on the box — and on which boxes, per breakpoint. Unset, the compiler decides it wherever the component stands side by side with a thing that draws a caption row (UIFieldBoxes); UIFieldBoxAlignment.None keeps it where it is laid out.
Render-time only. A panel draws it as its top padding and its least height, anything else as its top margin, set down onto the band's middle; an authored Padding, MinHeight or Margin replaces them.
Loading
SetLoading · BindLoading
bool?falseone-wayWhether the component is in loading state — a live state a controller turns on and off.
While it holds, by a static value or a controller binding, the server refuses a command or a value the component or anything inside it sends — as the page does.
LoadingStyle
SetLoadingStyle · BindLoadingStyle
UILoadingStyle?nullone-wayThe visual indicator shown while this component or spinner is loading, or null to inherit the ambient or theme loading style.
ShowContextMenu
SetShowContextMenu · BindShowContextMenu
bool?trueone-wayWhether a right-click opens the IVisualComponent.ContextMenu; on a host with rows, whether it opens any row's. Off, the menu stays in the tree and nothing opens it.
ActionBar
SetActionBar
UIActionBarAlignment?null—How the component's action bar lines up with it, or null for none: the IVisualComponent.ContextMenu's entries marked for the bar (a menu item's InActionBar) as icons, and "more" opening the menu itself, floating above the component once the reader chooses it — a press, a tap, the keyboard's cursor — until a press elsewhere, Escape, or another chosen.
A quick view of the menu, not a second list: a press on an icon is that entry's press. Render-time only; a component with an action bar and no context menu is refused when the view compiles.
ActionBarRepeatInMore
SetActionBarRepeatInMore
bool?true—Whether the menu the IVisualComponent.ActionBar's "more" opens repeats the entries the bar shows (the default), or holds the rest alone — no caption or rule left with nothing to stand over or between. A right-click and a long press open the whole menu either way, and a bar whose menu holds nothing more draws no "more".
Render-time only.
ScrollGroup
SetScrollGroup · BindScrollGroup
stringnullone-wayThe scroll group this component belongs to: every component sharing the name scrolls together.
Driven by whichever one the reader scrolls. Components that mark their shown source lines (e.g. a code field and a Markdown display) sync line-for-line; otherwise by scroll fraction.
TextSelectable
SetTextSelectable · BindTextSelectable
bool?nullone-wayWhether the reader can select the words in this component and everything inside it: true lets them (a table whose cells are copied, a chat bubble), false keeps them out; unset, the place decides — a Text's and a Paragraph's words and a validation message select, unless they stand in a row, a menu or another control, and nothing else does. The nearest component that says wins.
A control's own words (a button's label, a tab, a menu entry, a field's caption), a surface the pointer drags (a row that drags by itself, a canvas, a grip) and, on a touch screen, anything a long press opens a menu on never select; a field's value always does.
WindowFoot
SetWindowFoot
bool?null—Whether this component is the window's foot (a chat's composer, a pane's last row): where it stands at the window's bottom edge the phone's system bar takes its background colour, dimmed by any open modal drawer or dialog veil, and its content sits above the bar. The page's bottom bar is one by itself.
Render-time only.