# MediaQuery ## Description BitMediaQuery renders content by what the browser's matchMedia API reports, so a layout decision that CSS cannot express - rendering a different component, or none at all, rather than restyling one - is written once beside the markup it belongs to. It offers the predefined bit screen queries, built at runtime from the live theme breakpoints so a customized theme is honored, and accepts any custom media query, including the non-viewport features such as orientation, pointer or prefers-color-scheme. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | CascadingTheme | `BitTheme?` | null | The theme cascaded from an enclosing BitThemeProvider. Only its breakpoints are read, and only to resolve a ScreenQuery. They take precedence over the --bit-bp-* CSS variables of the rendered element, which is what keeps a scoped theme reachable when there is no element of the component's own to read them from (NoWrapper, or a usage with no content at all). | | ChildContent | `RenderFragment?` | null | The content of the element to render if the specified query is matched. | | DefaultMatched | `bool` | false | The initial matched state to render with until the actual result of the query arrives from the browser. Useful to avoid a flash of the wrong content during prerendering, where the query cannot be evaluated yet. Ignored when IsMatched is bound, since the value handed over is then the initial state already. | | IsMatched | `bool` | false | The current matched state of the provided query. This is an output of the component rather than an input: the browser owns the state, and the component writes the latest result it reports here. Set one way (without a Changed callback beside it) the value belongs to the page, which freezes the state; use DefaultMatched to seed it instead. (two-way bound) | | Matched | `RenderFragment?` | null | The content to be rendered if the provided query is matched (an alias for ChildContent). | | NotMatched | `RenderFragment?` | null | The content to be rendered if the provided query is not matched. | | NoWrapper | `bool` | false | Renders the active content directly, without the wrapping root element. Since no element is rendered, everything that describes one (class, style, id, dir, ...) is ignored. | | OnChange | `EventCallback<bool>` | | The event callback to be called when the state of the media query has been changed. It is also called once with the initial matched state, right after the query gets evaluated by the browser for the first time. | | Query | `string?` | null | Specifies the custom query to be matched. Any valid CSS media query is accepted, including non-viewport features such as orientation, pointer, or prefers-color-scheme. Takes precedence over ScreenQuery when both are provided. | | ScreenQuery | `BitScreenQuery?` | null | Defines the screen query to be matched, amongst the predefined Bit screen media queries. The actual query is built at runtime from the live theme breakpoints (the --bit-bp-* CSS variables), so customized theme breakpoints are honored. | | Template | `RenderFragment<bool>?` | null | The content to be rendered for both states of the query, receiving the current matched state. Since it stays one fragment in one place of the render tree, the content is updated rather than built again when the query flips, so the state the components inside it hold survives the change. Takes precedence over Matched, ChildContent and NotMatched. | | AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. | | Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. | | Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. | | ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. | | HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. | | Id | `string?` | null | Gets or sets the unique identifier for the component's root element. | | IsEnabled | `bool` | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. | | Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. | | TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. | | Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. | ## Public Members | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. | | RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. | ## Enums ### BitScreenQuery Enum | Name | Value | Description | | :--- | :--- | :---------- | | Xs | 0 | Extra small query: [@media screen and (max-width: 599.98px)] | | Sm | 1 | Small query: [@media screen and (min-width: 600px) and (max-width: 959.98px)] | | Md | 2 | Medium query: [@media screen and (min-width: 960px) and (max-width: 1279.98px)] | | Lg | 3 | Large query: [@media screen and (min-width: 1280px) and (max-width: 1919.98px)] | | Xl | 4 | Extra large query: [@media screen and (min-width: 1920px) and (max-width: 2559.98px)] | | Xxl | 5 | Extra extra large query: [@media screen and (min-width: 2560px)] | | LtSm | 6 | Less than small query: [@media screen and (max-width: 599.98px)] | | LtMd | 7 | Less than medium query: [@media screen and (max-width: 959.98px)] | | LtLg | 8 | Less than large query: [@media screen and (max-width: 1279.98px)] | | LtXl | 9 | Less than extra large query: [@media screen and (max-width: 1919.98px)] | | LtXxl | 10 | Less than extra extra large query: [@media screen and (max-width: 2559.98px)] | | GtXs | 11 | Greater than extra small query: [@media screen and (min-width: 600px)] | | GtSm | 12 | Greater than small query: [@media screen and (min-width: 960px)] | | GtMd | 13 | Greater than medium query: [@media screen and (min-width: 1280px)] | | GtLg | 14 | Greater than large query: [@media screen and (min-width: 1920px)] | | GtXl | 15 | Greater than extra large query: [@media screen and (min-width: 2560px)] | | SmToMd | 16 | Small through medium query: [@media screen and (min-width: 600px) and (max-width: 1279.98px)] | | SmToLg | 17 | Small through large query: [@media screen and (min-width: 600px) and (max-width: 1919.98px)] | | SmToXl | 18 | Small through extra large query: [@media screen and (min-width: 600px) and (max-width: 2559.98px)] | | MdToLg | 19 | Medium through large query: [@media screen and (min-width: 960px) and (max-width: 1919.98px)] | | MdToXl | 20 | Medium through extra large query: [@media screen and (min-width: 960px) and (max-width: 2559.98px)] | | LgToXl | 21 | Large through extra large query: [@media screen and (min-width: 1280px) and (max-width: 2559.98px)] | ### BitVisibility Enum | Name | Value | Description | | :--- | :--- | :---------- | | Visible | 0 | The content of the component is visible. | | Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). | | Collapsed | 2 | The component is hidden (display:none). | ### BitDir Enum | Name | Value | Description | | :--- | :--- | :---------- | | Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). | | Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). | | Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. | ## Examples \n**Basic**: ```razor The screen is wider than the Sm band (GtSm). The screen is narrower than the Md band (LtMd). ``` \n**Screen queries**: ```razor This is Xs (Extra Small). This is Sm (Small). This is Md (Medium). This is Lg (Large). This is Xl (Extra Large). This is Xxl (Extra Extra Large). This is LtSm (Less Than Small). This is LtMd (Less Than Medium). This is LtLg (Less Than Large). This is LtXl (Less Than Extra Large). This is LtXxl (Less Than Extra Extra Large). This is GtXs (Greater Than Extra Small). This is GtSm (Greater Than Small). This is GtMd (Greater Than Medium). This is GtLg (Greater Than Large). This is GtXl (Greater Than Extra Large). This is SmToMd (Small through Medium). This is SmToLg (Small through Large). This is SmToXl (Small through Extra Large). This is MdToLg (Medium through Large). This is MdToXl (Medium through Extra Large). This is LgToXl (Large through Extra Large). ``` \n**Matched & NotMatched**: ```razor This is Matched (BitScreenQuery.Md). [BitScreenQuery.Md] NotMatched!. ``` \n**Template**: ```razor ``` \n**Theme breakpoints**: ```razor Md is matched. Md is not matched. Md is matched. Md is not matched. ``` ```csharp private readonly BitTheme breakpointsTheme = new() { Layout = { Breakpoints = { Md = "700px", Lg = "900px" } } }; ``` \n**Custom query**: ```razor This is screen and (max-width: 999px). Not matched yet! The width is between 400px and 700px (range syntax). The width is outside the 400px to 700px range. ``` \n**Media features**: ```razor The screen is in landscape orientation. The screen is in portrait orientation. The system prefers a dark color scheme. The system prefers a light color scheme. The primary pointing device is precise (e.g. a mouse). The primary pointing device is coarse or absent (e.g. a touchscreen). Reduced motion is requested by the system. Reduced motion is not requested by the system. ``` \n**NoWrapper**: ```razor This content renders without a wrapping element (BitScreenQuery.GtSm). [BitScreenQuery.GtSm] NotMatched! (still no wrapping element) ``` \n**DefaultMatched**: ```razor This is Matched (BitScreenQuery.GtSm), also rendered before the query gets evaluated. [BitScreenQuery.GtSm] NotMatched!. ``` \n**Binding**: ```razor

The screen is currently @(isSmallScreen ? "small" : "wide") (BitScreenQuery.LtMd).

A button driven by the bound value ``` ```csharp private bool isSmallScreen; ``` \n**OnChange**: ```razor

[BitScreenQuery.Md] IsMatched?: @isMatched

[BitScreenQuery.Md] via the IsMatched property: @(mediaQueryRef?.IsMatched ?? false)

OnChange call count: @changeCount

``` ```csharp private bool isMatched; private int changeCount; private BitMediaQuery? mediaQueryRef; private void HandleOnChange(bool value) { isMatched = value; changeCount++; } ``` \n**Style & Class**: ```razor Styled through the Style parameter (GtXs). Styled through the Style parameter, not matched (GtXs). Classed through the Class parameter (GtXs). Classed through the Class parameter, not matched (GtXs). ``` \n**RTL**: ```razor این محتوا در صفحه‌های بزرگ‌تر از Xs نمایش داده می‌شود. عرض صفحه کمتر از حد GtXs است. ```