MediaQuery

The content of the component renders only while the screen matches the query it is given. ScreenQuery takes one of the predefined bit screen queries - here GtSm (everything above the Sm band) and LtMd (everything below the Md band), which between them cover every width - so a piece of markup is kept off the narrow screens, or off the wide ones, without a line of CSS. Resize the window to watch the two swap (zooming in and out works too).

The predefined screen queries come in four shapes: a single band (Xs to Xxl), everything below a breakpoint (Lt*), everything above one (Gt*), and a span between two of them (*To*). The bands never overlap, and each one ends two hundredths of a pixel below where the next one starts, which is close enough that one of the six is matched at any size in practice; the other three shapes are cut from the same breakpoints and do overlap, since each of them answers a different question about the same width. Resize the window to explore them all (zooming in and out works too).

Matched and NotMatched render different content for each state of the query, making an inline responsive if/else. Matched is an alias for ChildContent and takes precedence over it when both are provided, and either side may be left out: with only NotMatched the component renders nothing while the query matches, which is how a piece of markup is dropped above a breakpoint.

Template is the one fragment that spans both states, receiving the current matched state as its context. It is for the common case where the two states are the same markup told apart by a value - a size, a variant, a class, an attribute - and saves writing that markup twice.
Since it stays one fragment in one place of the render tree, the content is updated rather than torn down and built again when the query flips, so whatever the components inside it hold - a half filled in form, a scroll position - survives the change of the viewport. It takes precedence over Matched, ChildContent and NotMatched.

The predefined screen queries are not baked into the component: they resolve from the live theme breakpoints, so overriding them - globally through BitThemeManager, or for one subtree through BitThemeProvider - changes what the same ScreenQuery matches. Here the very same BitScreenQuery.Md answers to a different width range inside a provider that re-values the Md and Lg breakpoints. Resize the window and watch the two flip at different widths.

Query takes any valid CSS media query verbatim ( more info (opens in a new tab)), which is what covers the breakpoints that are not part of the theme scale, including the modern range syntax such as (400px <= width <= 700px). It takes precedence over ScreenQuery when both are set, and a query the browser cannot parse is reported as a warning in the developer console rather than silently never matching.

Media queries are not only about the viewport width, and neither is this component. Any media feature the browser understands works as a custom query and is watched the same way: the orientation of the screen, the color scheme the system prefers, how precise the pointing device is, or whether reduced motion is asked for. Each of these changes while the page is open, and the content follows it without a reload.

By default the active content renders inside a root div. NoWrapper removes it and renders the content directly, which is what keeps the component out of the way where the extra element would change the layout - a flex or grid container that lays out its own children, a table row, a list. Nothing that describes an element (the class, the style, the id, the direction) applies then, since there is none; a scoped BitThemeProvider is still honored, because the breakpoints are read from the cascading theme rather than from the missing element. Inspect the output below to see that no wrapper is there.

A media query can only be evaluated by the browser, so until the first answer arrives the component has to render something: by default the not-matched side. DefaultMatched flips that first guess so the matched content renders instead, which is what avoids a flash of the wrong content while a page is prerendered on the server or before the JavaScript runtime is up. The real result takes over as soon as it arrives, so pick the side the majority of the visitors will land on.

IsMatched is two-way bindable, which is the shortest way to hand the state of a query to the rest of a page: a field kept in step by @bind-IsMatched can drive anything, and the component itself needs no content at all. It is an output rather than an input - the browser owns the state - so bind it rather than setting it one way, and use DefaultMatched to seed the value before the first answer arrives.

OnChange reports every change of the matched state, and once more at the start with the initial result, right after the browser evaluates the query for the first time - so a handler always sees the real state and not only the changes after it. Use it where a change is an action to take (loading the data a wide layout needs, closing a drawer) rather than a value to hold; where it is a value, bind IsMatched instead, which is also readable at any time from a reference to the component.

Style and Class apply to the wrapping root element like they do on every other component of the library, so the box a matched query renders can be styled without an extra element around it. They are ignored while NoWrapper is set, since there is then no element of the component's own to carry them.

Dir sets the text direction of the wrapping root element, writing the dir attribute and, for right-to-left, the bit-rtl class the rest of the library reads. Like the other parameters that describe an element, it has no effect while NoWrapper is set - the surrounding direction then applies to the content as it stands.