Callout

The Anchor is what the callout is positioned against and what toggles it on a click, and Content (an alias of ChildContent) is what the callout holds. The anchor is a plain container around whatever is put in it, so it should hold the focusable element the user activates - a button, most of the time. IsEnabled turns the whole callout off, down to the Open, OpenAt and Toggle methods, and closes one that was already open.

NoOverlay leaves the page its own clicks while the callout is open, by not rendering the overlay that otherwise covers the page and takes the click that dismisses the callout. Whatever is underneath stays usable - an outside click still dismisses the callout, but it also reaches what it landed on. DefaultIsOpen is the state the callout starts in and then manages itself, so the third one here is already open when the page loads; it is given NoOverlay as well, since a callout that opens with the page would otherwise spend the first click made anywhere on it on dismissing itself.

The callout does not have to render its own anchor: AnchorId points it at the id of any element on the page and AnchorEl at an element reference, which is the one to reach for when the anchor has no id of its own. Both leave the opening to the consumer, so the callout is driven through its Toggle, Open and Close methods, or through IsOpen.

OpenAt opens the callout at a point on the screen instead of against an anchor, which is what a context menu needs. It takes the coordinates directly, or the mouse event they came from, so a right-click handler is the whole of it. The point is placed against exactly as an anchor would be, so the menu still flips to the side with the most room and is still kept within the screen. Calling it again while the callout is open moves it to the new point rather than closing and reopening it, and the anchor takes over again the next time anything else opens the callout.

A context menu is what NoOverlay is there for: with the overlay in the way, the second right-click would land on it, so the browser would show its own menu over the callout instead of the callout moving to the new point. The callout is still dismissed by an interaction outside of it - a click anywhere else on the page, or a right-click the page does not take for itself.

Last action: none

IsOpen is two-way bindable, so the open state can be owned by the page: anything can open the callout and its own content can close it. DefaultIsOpen, in the Basic example above, is the uncontrolled version of the same thing - the state the callout starts in, which it then manages itself - and it is only read when IsOpen is not bound.

OpenOnHover opens the callout when the pointer enters the anchor and closes it when the pointer leaves both the anchor and the callout, which is what a hover card is expected to do. HoverOpenDelay keeps a pointer that is only passing over the anchor from opening it, and HoverCloseDelay (150ms by default) bridges the gap between the anchor and the callout so that moving from one to the other does not close what the pointer is on its way to. The anchor keeps toggling the callout on a click, and the mode turns itself off on the touch screens, where hovering does not exist - so the keyboard and the finger are both left with a way in. The pointer is tracked over the anchor the callout renders itself, so this mode goes with Anchor rather than with an external one.

ShowArrow draws a beak on the edge of the callout that faces the anchor, centred on the anchor and kept clear of the rounded corners of the callout. It follows the callout wherever it is placed - above, below or beside the anchor - and is painted in the same color as the callout, border included. ArrowSize sets the side of the square it is cut out of, in pixels (12 by default), and a bigger beak is kept further from the corners of the callout so the rounding never cuts it. ArrowPadding is that distance from the corners (16px by default, never less than the arrow itself): a wider one pulls the beak back towards the middle of a callout aligned with the edge of a wide anchor, and a narrower one lets it sit closer to the corner and nearer to what it points at. Pair it with a Gap to leave the beak room to stand out of the anchor.

Direction declares which sides the callout may be placed on, and it picks the one with the most room among them: TopAndBottom (the default) keeps it above or below the anchor, while All also lets it move beside the anchor when neither of those has room, where it is aligned with the top of the anchor. Side asks for one side by name and wins over Direction where it has the room; it is a preference rather than a demand, so a callout that does not fit there is placed on the opposite side, and only when neither fits does Direction decide as usual - unless NoFlip holds it to the side it was asked for whatever the room there, which is what a layout that has to stay put needs. Alignment runs across that choice: it lines the callout up with the Start edge of the anchor (the default), with its Center, or with its End edge - horizontally for a callout above or below the anchor, vertically for one beside it - and the callout is still slid back onto the screen afterwards if the alignment would hang it off an edge. AlignmentOffset slides the callout along that same axis, inwards from whichever edge the alignment picked, so the same value moves a Start-aligned callout and an End-aligned one towards each other and a centered one not at all. Gap is the distance in pixels the callout keeps from the anchor, on whichever side it ends up on, and CollisionPadding is the distance it keeps from the edges of the screen - the room to leave around it, and around a fixed header or toolbar it should not end up under.

The placement is kept up to date for as long as the callout is open: it follows the page scrolling and resizing under it, the visible area changing as a mobile keyboard comes and goes, and an anchor that changes size, and it hides itself while its anchor is scrolled out of sight rather than pointing at nothing. Reposition covers what it cannot see - a content of its own that has grown or shrunk - and lays it out again without replaying its entry animation. MaxWindowWidth is the window width below which the callout may hang off the end of the screen instead of being slid back onto it, for the layouts that scroll sideways on narrow screens and would otherwise have the callout pulled away from the anchor it belongs to.

A callout is only as wide as its content needs by default. Width, MinWidth and MaxWidth take CSS values and size it directly - a width or a maximum width is one a long content wraps inside rather than stretching the callout past it - while MaxHeight caps it and scrolls whatever is left over. SetCalloutWidth widens the callout to at least the width of the anchor and FixedCalloutWidth holds it to at most that width, so a wider content wraps instead of stretching it; both are applied after the callout is measured, so they take precedence over Width.

Header and Footer lay the callout out as a column of the two of them around a body that takes the scrolling, so a title and a row of actions stay put while a long content scrolls between them. The callout wires the three parts up itself: the body is what is capped to the room the viewport leaves, less the heights of the header and the footer, so the callout is never taller than the screen it is shown on and nothing is cut off. The header is also what names the callout to the screen readers unless AriaLabel names it directly, which is the accessible name a callout that reports itself as a dialog is required to have.

The same layout can be built by hand out of the consumer's own elements, which is what a content with more than three parts to it needs: ScrollContainerId hands the scrolling over to an element inside the content, HeaderId and FooterId name the elements above and below it whose heights come off the cap, and ScrollOffset is any further vertical space to keep out of it. All three win over the parts the callout renders itself.

ResponsiveMode turns the callout into a panel on small screens (under 600px), which slides in from an edge of the screen and is swiped away along the same axis it slid in on. Panel takes its edge from PanelPosition - Start or End for a side panel - while Top and Bottom are sheets that come down from the top or up from the bottom. Point ScrollContainerId at the scrollable element inside the content so the swipe gesture does not fight its scrolling. Resize the window to see it.

Background paints the callout in one of the background color kinds of the library and Border draws a border in one of the border kinds; the beak of an arrowed callout takes both, so it always matches the surface it points out of. NoShadow drops the elevation, for a callout that leans on its border instead.

Modal dims the page behind the callout and holds it still while the callout is open, so the callout reads as the only thing in play - the wheel and the touch are the callout's, and the page cannot scroll the callout away underneath it. The overlay still dismisses it on a click, and pairing it with TrapFocus is what makes the callout modal to the keyboard and to the screen readers as well as to the eye.

The anchor carries the relationship of the callout for the screen readers (aria-haspopup, aria-controls and aria-expanded), and Escape closes the callout from either side of it - from inside the callout, and from the trigger in the anchor, where the focus stays unless the callout was asked to take it. Whenever the callout is closed while the focus is in it, the focus goes back to the anchor, so the keyboard never ends up at the top of the page.

AutoFocus moves the focus into the callout as soon as it opens, to its first focusable element - or to whichever element in the content carries a data-autofocus attribute, for the callouts whose first focusable element is not the one worth starting at - so a pointer user reaches the content without an extra Tab too. TrapFocus goes further and keeps the keyboard inside: Tab and Shift+Tab cycle within the callout instead of running on into the page behind it, and the callout reports itself as a modal dialog to the screen readers. It is what a callout hosting a form or a filter panel needs, and it implies AutoFocus. Role overrides the ARIA role for the cases those two do not cover, and AriaLabel names the callout where its content does not - which makes it a group unless a role of its own says otherwise, since a name on a plain container is one no screen reader announces. A callout that renders a Header is named by it without either of the two, so a dialog always has the accessible name it is required to have. The rest is wired up on its own: the trigger inside the anchor reports the callout with aria-controls and aria-expanded, and it names what it opens with aria-haspopup only where the callout really is one of the kinds that property can name - a dialog, a menu, a listbox, a tree or a grid.

A callout is dismissed by a click outside of it, by the Escape key, and by the page scrolling or resizing under it. AutoClose adds a click inside it to that list, which is what an action list is expected to do: picking an item completes the interaction. NoDismissOnEscape and NoDismissOnOutsideClick each take one of the ways out away - the second also stops a scroll or a resize from dismissing it, re-anchoring it to its anchor instead - for the callouts that are only meant to be closed through their own content.

Opening a callout normally takes over from the one that is already open, which is how two unrelated callouts stay from piling up on each other. A callout whose anchor lives inside another one is the exception: it is nested in it, so the outer callout stays open underneath it, and any number of levels can be stacked that way. Everything that follows from being open follows the stack too - dismissing the outer callout takes the inner ones with it, Escape peels off the innermost one, and a scroll or a resize re-anchors all of them at once. Any component that opens a callout of its own nests the same way, so a dropdown, a date picker or a menu button can sit inside a callout without closing it.

The content of a callout is in the page whether the callout is open or not, so that whatever state it holds survives the callout closing. LazyRender keeps it out until the callout is first opened, for the contents expensive enough that rendering one behind a closed callout is a cost of its own - a calendar, a long list, a chart. It is only the first opening that is deferred: the content stays from then on, so its state still survives every close after that.

OnToggle fires on every change of the open state and is handed the new one, while OnOpen and OnDismiss split that in two. All three fire however the callout was closed: an outside click, the Escape key, a swipe on a responsive panel, or another callout taking over.

Toggled: 0, Opened: 0, Dismissed: 0

Style and Class land on the root element, which is the container of the anchor - the callout itself is rendered outside of it and relocated to the body while it is open, so the way to reach it is Styles and Classes. Those carry a value per part: Root, AnchorContainer, Content, Header, Body, Footer, Arrow, Overlay, and Opened, which is applied to the root only while the callout is open.

Where the callout ended up is on the callout and on its arrow as it is laid out, so a style can follow the placement without knowing it in advance: data-bit-cal-pos is the physical side of the anchor the callout was placed on (below, above, left or right) and data-bit-cal-align is how it was lined up across that side (start, center or end). Both are rewritten on every layout pass, so a callout that flips while it is open never keeps the side it started on.

Set Dir to BitDir.Rtl to lay the callout out right-to-left. The direction travels with the callout to the body, where it is relocated while it is open, so its content is laid out in it too; the placement mirrors along with it, aligning the callout with the right edge of its anchor and preferring the left side when it has to move beside it.