Extras
ImageViewer
Bit.BlazorUI.ExtrasZoomableImagePanZoomImageZoom
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.
Notes
To use this component, you need to install the
Bit.BlazorUI.Extras(opens in a new tab)
nuget package, as described in the Optional steps of the
Getting started page.
Zoom 1 is the image fitted in the frame: as large as fits, never larger than it is. The frame is a tab stop of
its own: + and - zoom, the arrow keys move a zoomed image, and 0 fits it again. The plain wheel is left to the
page, so it still scrolls past the viewer; Ctrl+wheel (Cmd+wheel on a Mac) and a trackpad pinch zoom it.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
Zoom with the buttons, Ctrl+wheel, a pinch or a double-click; drag the zoomed image around. Tab to the frame
to do the same from the keyboard.
100%
Binding
Zoom is two-way bindable: it follows every gesture, and setting it zooms the image around its center.
100%
Zoom: 1
Zoom range
MinZoom and MaxZoom are the range, as multiples of the fitted image: a MinZoom below 1 lets the image get
smaller than the frame. ZoomFactor is a step of the buttons and the keys, and DoubleClickZoom where a
double-click goes.
100%
Wheel zoom
WheelZoom zooms with the plain wheel too, for a viewer with no page around it to scroll: one that fills the
screen, or sits in a dialog.
100%
Full screen
ShowFullScreenButton adds a button to the toolbar that shows the viewer over the whole page, as a dialog the
focus is kept inside, which a plain Escape or its close button leaves. FullScreen is two-way bindable, and the
plain wheel zooms a full screen viewer.
100%
FullScreen: False
Lightbox
FullScreenOnly leaves the viewer out of the page until it is full screen: a lightbox the page opens from a
thumbnail of its own, which the focus goes back to as it closes.
Plus and minus zoom, arrow keys move a zoomed image, 0 fits it again.
100%
Public API
NoToolbar leaves the zoom buttons out, and ZoomIn, ZoomOut, Reset and EnterFullScreen do the same from code.
Height
Height is the height of the frame, as any CSS value.
100%
Disabled
A disabled viewer neither zooms nor pans, and takes no focus.
100%
Texts
Texts is every word the viewer says: the names of its buttons and the instructions of its keyboard.
100%
Style & Class
Classes and Styles reach every part of the viewer, and the --bit-ImageViewer-* variables restyle its defaults.
100%
100%
RTL
Use BitImageViewer in right-to-left (RTL).
100%
CSS variables
The public custom properties this component reads off its root, for what no parameter covers.
Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property:
set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it,
or on the Style of one instance to restyle it - and any instance nested inside it, which inherits the value too; a parameter changes one alone,
as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps
one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or
font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component
falls back to the theme token beside it.
BitImageViewer CSS variables
| 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. |
API
Every parameter, public member, sub-class and enum this component exposes.
BitImageViewer 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. |
BitImageViewer 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. |
BitComponentBase parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| 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. |
BitComponentBase 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. |
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. |
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. |
Feedback
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.