# Image
## Description
BitImage is an img inside a frame, and nearly everything it offers is about the relationship between the two. The frame takes the size (Width, Height, AspectRatio, MaximizeFrame) and the shape (Rounded, Circular, Bordered) and clips what falls outside it, while ImageFit and ImagePosition decide what the image does inside it when the two are different shapes. The other half is what happens before the image is there: the component follows the browser's load and error events, hides the image until it has arrived, fades it in, holds the frame with a blurred placeholder or a loading template, and tries a fallback source before it gives up. What the browser itself decides stays the browser's: lazy loading, decoding, fetch priority and the srcset/sizes responsive picture are all reachable as parameters.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Alt | `string?` | null | Specifies an alternate text for the image. The attribute is always rendered, so an image given no text is announced as decorative (alt="") rather than read out as a file name. |
| AspectRatio | `string?` | null | The aspect ratio of the frame of the image, as a CSS aspect-ratio value (e.g. "16/9" or "1"). Reserves the room the image will need before it arrives. |
| Bordered | `bool` | false | Renders a border around the frame of the image. |
| ChildContent | `RenderFragment?` | null | The content rendered over the image, filling the frame. |
| Circular | `bool` | false | Renders the frame of the image as a circle. Takes precedence over Rounded. |
| Classes | `BitImageClassStyles?` | null | Custom CSS classes for different parts of the BitImage. |
| Cover | `BitImageCover?` | null | Specifies the cover style to be used for this image. Only the CenterCover and CenterContain fits read it. |
| CrossOrigin | `BitImageCrossOrigin?` | null | Specifies the CORS setting the image is requested with. |
| Decoding | `BitImageDecoding?` | null | Hints the browser at whether the image may be decoded asynchronously. |
| Draggable | `bool?` | null | Specifies whether the image can be dragged by the user. |
| ErrorTemplate | `RenderFragment?` | null | The custom template used to show the error state of the image. |
| FadeIn | `bool` | false | If true, fades the image in when it becomes visible. |
| FallbackSrc | `string?` | null | The source of the image to show when the one given by Src fails to load, or when no Src is given at all. It is tried exactly once. |
| FetchPriority | `BitImageFetchPriority?` | null | Hints the browser at the priority this image is fetched with, relative to the other resources of the page. |
| Height | `string?` | null | The image height value. A bare number is read as a pixel count; anything else is used as written. |
| ImageAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Capture and render additional attributes in addition to the image's parameters. The dictionary is merged with the attributes the component builds itself rather than replaced by them. |
| ImageFit | `BitImageFit?` | null | Used to determine how the image is scaled and cropped to fit the frame. |
| ImagePosition | `string?` | null | The position of the image inside its frame, as a CSS object-position value (e.g. "top", "50% 25%"). It decides which part of the image survives a crop. |
| Loading | `BitImageLoading?` | null | Allows for browser-level image loading (lazy or eager). |
| LoadingTemplate | `RenderFragment?` | null | The custom template used to show the loading state of the image. |
| MaximizeFrame | `bool` | false | If true, the image frame will expand to fill its parent container. |
| OnClick | `EventCallback<MouseEventArgs>` | null | Callback for when the image is clicked. Assigning it makes the image a focusable button that also answers the Enter and Space keys. |
| OnError | `EventCallback` | null | Callback for when the image fails to load, including the failure that is answered by falling back to the FallbackSrc. |
| OnLoad | `EventCallback` | null | Callback for when the image has been loaded successfully. |
| OnLoadingStateChange | `EventCallback<BitImageState>` | null | Optional callback method for when the image load state has changed. |
| PlaceholderSrc | `string?` | null | The source of a placeholder image shown, blurred, while the image itself is still loading. |
| ReferrerPolicy | `BitImageReferrerPolicy?` | null | Specifies how much of the address of the current page is sent to whoever serves the image. |
| Rounded | `bool` | false | Rounds the corners of the frame of the image. |
| Shadow | `bool` | false | Renders a shadow under the frame of the image, lifting it off the surface it sits on. |
| Sizes | `string?` | null | The value of the sizes attribute of the image, which tells the browser how wide the image will be laid out at before it knows the layout. |
| Sources | `IEnumerable<BitImageSource>?` | null | The alternative sources of the image, offered to the browser ahead of Src. This is the art-direction and the format-negotiation half of responsive images, which Srcset cannot express. |
| Src | `string?` | null | Specifies the src of the image. Changing it returns the component to the Loading state. |
| Srcset | `string?` | null | The set of image sources the browser may choose from, with their width or density descriptors (e.g. "photo-480.jpg 480w, photo-960.jpg 960w"). |
| StartVisible | `bool` | false | If true, the image starts as visible and is hidden on error. Otherwise, the image is hidden until it is successfully loaded. |
| Styles | `BitImageClassStyles?` | null | Custom CSS styles for different parts of the BitImage. |
| Title | `string?` | null | The title to show when the mouse is placed on the image. |
| Width | `string?` | null | The image width value. A bare number is read as a pixel count; anything else is used as written. |
| 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 |
| :--- | :--- | :------------ | :---------- |
| FocusAsync | `ValueTask` | | Gives the browser focus to the img element of the component. Only a clickable image (one with an OnClick) or one given an explicit TabIndex is focusable at all, so anywhere else the call does nothing. |
| ImageElement | `ElementReference` | | The reference to the img element of the component, for whatever has to reach the picture itself rather than the frame around it. RootElement is that frame. |
| LoadingState | `BitImageState` | BitImageState.Loading | The current loading state of the image. |
| ReloadAsync | `Task` | | Requests the image again from the beginning, whichever state it is in: the component returns to the Loading state, forgets that a FallbackSrc has been tried, and replaces the img element rather than patching it - which is what makes the browser fetch a source it already holds an answer for. |
| 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
### BitImageFit Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| None | 0 | Neither the image nor the frame are scaled. The image keeps its natural size and whatever of it does not fit the frame is cropped away from the right and the bottom. |
| Center | 1 | The image is not scaled. The image is centered and cropped within the content box. |
| CenterContain | 2 | The image will be centered horizontally and vertically within the frame and maintains its aspect ratio, scaled down where needed so that all of it fits inside the frame. |
| CenterCover | 3 | The image will be centered horizontally and vertically within the frame and maintains its aspect ratio, scaled up where needed so that it covers the frame and the overflow is cropped. |
| Contain | 4 | The image is scaled to maintain its aspect ratio while being fully contained within the frame. |
| Cover | 5 | The image is scaled to maintain its aspect ratio while filling the frame. |
| Fill | 6 | The image is stretched to fill the frame exactly, without maintaining its aspect ratio. |
| ScaleDown | 7 | The image is contained within the frame, but never scaled up: an image smaller than the frame keeps its natural size. |
### BitImageCover Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Landscape | 0 | The image will be shown at 100% height of container and the width will be scaled accordingly. |
| Portrait | 1 | The image will be shown at 100% width of container and the height will be scaled accordingly. |
### BitImageState Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Loading | 0 | The image is loading from its source. |
| Loaded | 1 | The image has been loaded successfully. |
| Error | 2 | An error has been encountered while loading the image. Where a FallbackSrc is provided, this state is only reached once that one has failed as well. |
### BitImageLoading Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Eager | 0 | The default behavior, eager tells the browser to load the image as soon as the img element is processed. |
| Lazy | 1 | Tells the user agent to hold off on loading the image until the browser estimates that it will be needed imminently. |
### BitImageDecoding Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Auto | 0 | The default behavior, which leaves the decision to the browser. |
| Sync | 1 | Decodes the image synchronously, so it is presented together with the rest of the content rendered in the same frame. |
| Async | 2 | Decodes the image asynchronously, so the rest of the content is not held back while the decoding runs. |
### BitImageFetchPriority Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Auto | 0 | The default behavior, which leaves the priority to the browser's own heuristics. |
| High | 1 | Fetches the image ahead of the other images of the page, for the one that is the page's largest contentful paint. |
| Low | 2 | Fetches the image after the other images of the page, for the ones that carry no meaning on the first screen. |
### BitImageCrossOrigin Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Anonymous | 0 | Sends a cross-origin request with no credentials: no cookie, no client certificate and no HTTP authentication. |
| UseCredentials | 1 | Sends a cross-origin request with credentials. The other origin has to answer with the matching Access-Control-Allow-Credentials header. |
### BitImageReferrerPolicy Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| NoReferrer | 0 | Sends no Referer header at all. |
| NoReferrerWhenDowngrade | 1 | Sends the full URL, except to a less secure destination (HTTPS to HTTP), where nothing is sent. |
| Origin | 2 | Sends only the origin - the scheme, the host and the port - of the current page. |
| OriginWhenCrossOrigin | 3 | Sends the full URL to the same origin, and only the origin to any other one. |
| SameOrigin | 4 | Sends the full URL to the same origin, and nothing at all to any other one. |
| StrictOrigin | 5 | Sends only the origin, and nothing to a less secure destination (HTTPS to HTTP). |
| StrictOriginWhenCrossOrigin | 6 | The default behavior: the full URL to the same origin, the origin alone to another secure one, and nothing to a less secure destination. |
| UnsafeUrl | 7 | Sends the full URL to every destination, secure or not. |
### 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. |
## Sub Classes
### BitImageClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the image. |
| Placeholder | `string?` | null | Custom CSS classes/styles for the placeholder image element, which is only rendered while a PlaceholderSrc is provided and the image itself has not loaded yet. |
| Image | `string?` | null | Custom CSS classes/styles for the image element. |
| LoadingTemplate | `string?` | null | Custom CSS classes/styles for the element wrapping the LoadingTemplate of the image. |
| ErrorTemplate | `string?` | null | Custom CSS classes/styles for the element wrapping the ErrorTemplate of the image. |
| Content | `string?` | null | Custom CSS classes/styles for the overlay element that holds the ChildContent of the image. |
### BitImageSource Properties
One alternative source of the image, rendered as a source element of the picture the image is then wrapped in. The browser walks the sources in order and takes the first one whose Media and Type it is satisfied by.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Srcset | `string?` | null | The set of images this source offers, with their width or density descriptors (e.g. "photo-480.avif 480w, photo-960.avif 960w"). This is the only required member. |
| Media | `string?` | null | The media query the source applies to (e.g. "(max-width: 600px)"). A source with none applies whatever the viewport is, so it belongs last among the sources that carry one. |
| Sizes | `string?` | null | How wide the image will be laid out at, for the browser to choose among a width-descriptor Srcset with. |
| Type | `string?` | null | The MIME type of the images this source offers (e.g. "image/avif"). A browser that cannot read the type skips the source without fetching anything. |
| Width | `int?` | null | The intrinsic width, in pixels, of the images this source offers. |
| Height | `int?` | null | The intrinsic height, in pixels, of the images this source offers. |
## Examples
\n**Basic**:
```razor
Load a slow image
Load a broken image
Reload both
}
@if (loadError)
{
loading...
The image could not be loaded.
}
```
```csharp
private bool loadLoading;
private bool loadError;
private string loadingStateText = "Loading";
private BitImage? slowImage;
private BitImage? brokenImage;
private async Task ReloadImages()
{
if (slowImage is not null)
{
await slowImage.ReloadAsync();
}
if (brokenImage is not null)
{
await brokenImage.ReloadAsync();
}
}
```
\n**FallbackSrc**:
```razor
@(loadPlaceholder ? "Reset" : "Load the image")
@if (loadPlaceholder)
{
Load again
```
\n**Style & Class**:
```razor
```
State: @loadingStateText
@if (loadLoading)
{
Clicked @clickCount times
```
```csharp
private int clickCount;
```
\n**ChildContent**:
```razor
A caption laid over the image
نوشتهای روی تصویر