# ImageViewer
**Also known as:** ZoomableImage, PanZoom, ImageZoom
## Description
BitImageViewer shows an image in a frame it can be zoomed and panned in: with Ctrl+wheel, a pinch, a double-click, the + and - keys or its zoom buttons, and moved around by dragging it or with the arrow keys while it is zoomed in.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Alt | `string?` | null | The alternative text of the image, which also names the viewer where it has no AriaLabel. |
| Classes | `BitImageViewerClassStyles?` | null | Custom CSS classes for the different parts of the image viewer. |
| DoubleClickZoom | `double` | 2 | The zoom a double-click (or a double tap) goes to, at the point it lands on, and back to fitted from any zoom above it. |
| FullScreen | `bool` | false | Shows the viewer over the whole page, as a modal dialog: the focus is kept inside it, the page behind it holds still, the plain wheel zooms, and a plain Escape or the close button leaves it, handing the focus back to where it was. Two-way bindable. It covers the page only from where no ancestor makes a frame of its own for fixed elements (a transform, a filter or containment). |
| FullScreenOnly | `bool` | false | Leaves the viewer out of the page until it is FullScreen, for a lightbox the page opens from a thumbnail of its own. |
| Height | `string?` | null | The height of the frame the image is shown in, as a CSS value (e.g. "24rem"). Default: the --bit-ImageViewer-height variable, else 20rem. A full screen viewer fills the screen instead. |
| MaxZoom | `double` | 8 | The largest zoom, as a multiple of the fitted image. |
| MinZoom | `double` | 1 | The smallest zoom, as a multiple of the fitted image: 1 is the fitted image itself. |
| NoToolbar | `bool` | false | Leaves the zoom buttons out, for a viewer operated by the pointer and the keyboard alone. |
| ShowFullScreenButton | `bool` | false | Adds a button to the toolbar that shows the viewer FullScreen, and back. |
| Src | `string?` | null | The URL of the image. A new one starts fitted again. |
| Styles | `BitImageViewerClassStyles?` | null | Custom CSS styles for the different parts of the image viewer. |
| Texts | `BitImageViewerTexts?` | null | The words of the viewer: the names of its buttons and the instructions of its keyboard. |
| WheelZoom | `bool` | false | Zooms with the plain wheel too, not only with Ctrl (or Cmd) held. Off by default, since the wheel is what scrolls the page the viewer sits in. A FullScreen viewer zooms with the plain wheel either way. |
| Zoom | `double` | 1 | The zoom, as a multiple of the image fitted in the frame. Two-way bindable. |
| ZoomFactor | `double` | 1.25 | The factor a step of the buttons and the + and - keys multiplies or divides the zoom by. |
| 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. |
| Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| 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. An attribute written on the component wins over an entry of the same name. |
| Id | `string?` | null | Gets or sets the unique identifier for the component's root element. |
| 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 |
| :--- | :--- | :------------ | :---------- |
| ZoomIn | `() => Task` | | Zooms in by one step (ZoomFactor), around the center of the frame. |
| ZoomOut | `() => Task` | | Zooms out by one step (ZoomFactor), around the center of the frame. |
| Reset | `() => Task` | | Fits the image in the frame again: zoom 1, centered. |
| EnterFullScreen | `() => Task` | | Shows the viewer over the whole page (FullScreen), unless it is disabled. |
| ExitFullScreen | `() => Task` | | Shows the viewer back in the page, handing the focus back to where it was before it went full screen. |
| 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
### 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
### BitImageViewerTexts Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| RoleDescription | `string` | "image viewer" | What the viewer is announced as, after its name. |
| Instructions | `string` | "Plus and minus zoom, arrow keys move a zoomed image, 0 fits it again." | How the viewer is operated from the keyboard, which a screen reader reads once the viewer has the focus. |
| ToolbarAriaLabel | `string` | "Zoom" | The name of the group of the zoom buttons. |
| ZoomIn | `string` | "Zoom in" | The name of the zoom in button. |
| ZoomOut | `string` | "Zoom out" | The name of the zoom out button. |
| Reset | `string` | "Fit to view" | The name of the button that fits the image in the viewer again. |
| EnterFullScreen | `string` | "Full screen" | The name of the button that shows the viewer full screen. |
| ExitFullScreen | `string` | "Exit full screen" | The name of the buttons that show a full screen viewer back in the page. |
### BitImageViewerClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the BitImageViewer. |
| Viewport | `string?` | null | Custom CSS classes/styles for the viewport of the BitImageViewer, the frame the image is zoomed and panned in. |
| Image | `string?` | null | Custom CSS classes/styles for the image of the BitImageViewer. |
| Toolbar | `string?` | null | Custom CSS classes/styles for the toolbar of the BitImageViewer. |
| Button | `string?` | null | Custom CSS classes/styles for each button of the toolbar of the BitImageViewer. |
| ZoomText | `string?` | null | Custom CSS classes/styles for the zoom level shown in the toolbar of the BitImageViewer. |
| FullScreen | `string?` | null | Custom CSS classes/styles for the root element of the BitImageViewer while it is full screen. |
| CloseButton | `string?` | null | Custom CSS classes/styles for the close button of a full screen BitImageViewer. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| Name | Default Value | Description |
| :--- | :------------ | :---------- |
| `--bit-ImageViewer-height` | 20rem | Height of the frame, where no Height is given. |
| `--bit-ImageViewer-background` | var(--bit-clr-bg-ter) | Fill of the frame around the image. |
| `--bit-ImageViewer-radius` | var(--bit-shp-radius-surface) | Corner radius of the frame. |
| `--bit-ImageViewer-button-size` | spacing(4) | Width and height of a toolbar button. |
| `--bit-ImageViewer-button-hover-background` | var(--bit-clr-bg-sec-hover) | Fill of a toolbar button under the pointer. |
| `--bit-ImageViewer-focus-color` | var(--bit-clr-pri-focus) | Focus ring of the frame and the buttons. |
| `--bit-ImageViewer-fullscreen-background` | var(--bit-clr-bg-pri) | Surface a full screen viewer covers the page with. |
| `--bit-ImageViewer-fullscreen-padding` | spacing(2) | Room around the frame of a full screen viewer. |
## Examples
\n**Basic**:
```razor
Zoom: @boundZoom.ToString("0.##")
Zoom to 3
```
```csharp
private double boundZoom = 1;
```
\n**Zoom range**:
```razor
FullScreen: @isFullScreen
```
```csharp
private bool isFullScreen;
```
\n**Lightbox**:
```razor
@foreach (var photo in photos)
{
}
ZoomIn
ZoomOut
Reset
EnterFullScreen
```
```csharp
private BitImageViewer viewerRef = default!;
```
\n**Height**:
```razor