ImageViewerAPI
Interface: ImageViewerAPI
Defines Image Viewer API.
Properties
actualSize
readonly actualSize: Size;
Gets the actual display size of the active image, including the active zoom value.
adaptiveNaturalSize
readonly adaptiveNaturalSize: Size;
Gets the active image DPI adaptive natural size. This is the image size that will be used to display the image at 100%. The adaptiveNaturalSize property is used for the actual size calculations.
eventBus
readonly eventBus: EventBus;
Image viewer event bus.
Example
viewer.eventBus.on("after-open", function(args) {
console.log("Image opened.", args);
});
viewer.open('Test.png');
frameIndex
frameIndex: number;
Gets or sets the active frame index. This is applicable for multi-frame images such as TIFF and ICO.
When setting this value, it will also be used as the initial frame index when opening a new image.
Example
const viewer = new DsImageViewer('#root');
viewer.frameIndex = 9;
viewer.open('Test.ico');
framesCount
readonly framesCount: number;
Gets total frames count for the active image. Applicable for TIFF, ICO images.
Example
const viewer = new DsImageViewer('#root');
viewer.onAfterOpen.register(function() {
alert("The image opened. Total number of frames: " + viewer.framesCount);
});
viewer.open('Test.png');
hasImage
readonly hasImage: boolean;
Indicates whether the viewer has opened the image.
Example
const hasImageFlag = viewer.hasImage;
hasRedo
readonly hasRedo: boolean;
Gets a value indicating whether the image viewer can redo changes.
Example
if(viewer.hasRedo) {
viewer.redo();
}
hasUndo
readonly hasUndo: boolean;
Gets a value indicating whether the image viewer can undo changes.
Example
if(viewer.hasUndo) {
viewer.undo();
}
isAnimationStarted
readonly isAnimationStarted: boolean;
Gets a value indicating whether the image animation has started.
Example
// Toggle image animation:
const viewer = DsImageViewer.findControl("#root");
if(viewer.isAnimationStarted) {
viewer.stopAnimation();
} else {
viewer.startAnimation();
}
language
readonly language: string;
language - A property that retrieves the standardized language key based on the provided language option.
The language key is determined by the options.language setting.
Returns
Standardized language key (e.g., 'en', 'ja').
layers
readonly layers: ImageLayer[];
Image layers. Used for painting.
naturalSize
readonly naturalSize: Size;
Gets the active image natural size. The natural size is the image's width/height if drawn with nothing constraining its width/height, this is the number of CSS pixels wide the image will be.
onAfterOpen
readonly onAfterOpen: EventFan;
The event raised when the user changes the viewer theme.
Example
const viewer = new DsImageViewer('#root');
viewer.onAfterOpen.register(function() {
alert("The image opened.");
});
viewer.open('Test.png');
onBeforeOpen
readonly onBeforeOpen: EventFan;
Occurs immediately before the image opens.
Example
const viewer = new DsImageViewer('#root');
viewer.onBeforeOpen.register(function(args) {
alert("A new image will be opened,\n payload type(binary or URL): " + args.type +",\n payload(bytes or string): " + args.payload);
});
viewer.open('Test.png');
onError
readonly onError: EventFan;
The event indicating error.
Example
function handleError(args) {
console.error(args);
}
const viewer = new DsImageViewer('#root');
viewer.onError.register(handleError);
viewer.open('Test.png');
onImagePaint
readonly onImagePaint: EventFan;
The event raised when appearance image element changed.
openParameters
readonly openParameters: OpenParameters;
The Open parameters that were used to open an image.
options
options: Partial<ViewerOptions>;
Viewer options
toolbarLayout
toolbarLayout: ImageToolbarLayout;
Defines the layout of the toolbar. The full list of the viewer specific toolbar items:
'open', '$navigation', 'navigation-auto', '$split', 'zoom', '$fullscreen', 'save', 'about'
Example
// Customize the toolbar layout:
viewer.toolbarLayout.viewer.default = ["open", "$zoom", "$fullscreen", "save", "print", "about"];
viewer.applyToolbarLayout();
undoCount
readonly undoCount: number;
Gets total undo levels count.
Example
alert("Undo levels count is " + viewer.undoCount);
undoIndex
readonly undoIndex: number;
Gets current undo level index.
Example
alert("The current Undo level index is " + viewer.undoIndex);
undoStorage
readonly undoStorage: UndoStorage;
Command based undo state storage.
Example
const isUndoInProgress = viewer.undoStorage.undoInProgress;
version
readonly version: string;
Returns the current version of the DS Image viewer.
Example
alert("The DsImageViewer version is " + viewer.version);
zoom
zoom: ZoomSettings;
Gets or sets the current zoom settings
Methods
addKeyboardListener()
addKeyboardListener(uniqueKey, handler): void;
Add window keyboard listener.
Parameters
uniqueKey
string
Listener key.
handler
Keyboard event handler.
Returns
void
addPlugin()
addPlugin(plugin): boolean;
Adds a plugin instance to the DsImageViewer. This method is now intended for internal and officially supported plugins only. Custom or third-party plugins are no longer supported starting from version 9.0. The plugin system remains available for internal use to provide optional viewer features, such as ImageFiltersPlugin, PageToolsPlugin, and PaintToolsPlugin. Attempting to register non-official plugins may lead to undefined behavior and is not supported by the product team.
Parameters
plugin
The plugin instance
Returns
boolean
true if added successfully; otherwise false.
Example
// ✅ Supported (built-in plugin)
const viewer = new DsImageViewer("#root");
viewer.addPlugin(new ImageFiltersPlugin());
// ❌ Not supported (custom plugin)
viewer.addPlugin(new CustomPlugin()); // Custom plugins are no longer supported
applyOptions()
applyOptions(): void;
Call this method in order to apply changed options.
Returns
void
Example
viewer.applyOptions();
applyToolbarLayout()
applyToolbarLayout(): void;
Call this method in order to apply changes in @see:toolbarLayout.
Returns
void
Examples
viewer.toolbarLayout.viewer.default = ["open", "save"];
viewer.applyToolbarLayout();
const viewer = new DsImageViewer(document.querySelector("#viewer"));
const toolbar = viewer.toolbar;
const toolbarLayout = viewer.toolbarLayout;
toolbar.addItem({
key: 'custom-action',
icon: { type: "svg", content: '<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="24" height="24" viewBox="0 0 24 24"><path style="fill: #205F78;" d="M20.25 12l-2.25 2.25 2.25 2.25-3.75 3.75-2.25-2.25-2.25 2.25-2.25-2.25-2.25 2.25-3.75-3.75 2.25-2.25-2.25-2.25 2.25-2.25-2.25-2.25 3.75-3.75 2.25 2.25 2.25-2.25 2.25 2.25 2.25-2.25 3.75 3.75-2.25 2.25 2.25 2.25z"></path></svg>' },
title: 'Custom action',
checked: false, enabled: false,
action: function () {
alert("Implement your action here.");
},
onUpdate: function (args) {
return {
enabled: true,
checked: false,
title: 'Custom action title'
}
}
});
toolbarLayout.viewer.default.splice(0, 0, "custom-action");
viewer.applyToolbarLayout();
clearUndo()
clearUndo(): void;
Clear undo storage.
Returns
void
close()
close(): Promise<void>;
Closes the currently open image.
Returns
Promise<void>
Example
await viewer.close();
configurePluginMainToolbar()
configurePluginMainToolbar(pos, buttonsToInsert): void;
Allows to configure the main toolbar layout.
Parameters
pos
number | boolean
The position where the buttons should be inserted. Use false or -1 to skip insertion. Undefined means the position will be determined automatically.
buttonsToInsert
string[]
An array of button keys to be inserted.
Returns
void
Example
// Apply a custom layout to insert "zoomIn" and "zoomOut" buttons at position 2 for the "PaintTools" plugin.
viewer.configurePluginMainToolbar(2, ["zoomIn", "zoomOut"]);
confirm()
confirm(
confirmationText?,
level?,
title?,
buttons?): Promise<boolean | ConfirmButton>;
Display confirmation dialog.
Parameters
confirmationText?
any
Confirmation text can be plain string or JSX.Element if you're using React.
level?
"error" | "info" | "warning"
title?
string
buttons?
Returns
Promise<boolean | ConfirmButton>
Example
const confirmResult = await viewer.confirm("Apply changes?", "info", "Confirm action", ["Yes", "No", "Cancel"]);
if (confirmResult === "Yes") {
// put your code here
} else if (confirmResult === "No") {
// put your code here
} else {
// put your code here
}
dataUrlToImageData()
dataUrlToImageData(dataUrl, destinationSize?): Promise<ImageData>;
Load image data using given data url.
Parameters
dataUrl
string
destinationSize?
Defines needed image size
Returns
Promise<ImageData>
dispose()
dispose(): void;
Use this method to close and release resources occupied by the DsImageViewer.
Returns
void
ensurePaintLayer()
ensurePaintLayer(): ImageLayer;
Create at least one image layer which will be used for painting.
Returns
executeCommand()
executeCommand(command): Promise<void>;
Execute a new command.
Parameters
command
Instance of a command.
Returns
Promise<void>
findPlugin()
findPlugin(pluginId): ImageViewerPluginReference;
Finds a viewer plugin by its id.
Parameters
pluginId
Plugin id
Returns
Example
// find imageFilters plugin:
const imageFilters = viewer.findPlugin("imageFilters");
// find pageTools plugin:
const pageTools = viewer.findPlugin("pageTools");
getEvent()
getEvent(eventName): EventFan;
Get event object.
Parameters
eventName
string
Embedded or custom event name.
Returns
Example
viewer.getEvent("CustomEvent").register(function(args) {
console.log(args);
});
getEventCanvasPoint()
getEventCanvasPoint(event, includeDpi): PointLocation;
Retrieves the point location from the pointer event provided by the 'event' parameter. The returned point is relative to the active canvas element.
Parameters
event
MouseEvent | PointerEvent
DOM Pointer or Mouse event object.
includeDpi
boolean
Returns
getImageDataUrl()
getImageDataUrl(): string;
Get current image data url.
Returns
string
getOriginalImageDataUrl()
getOriginalImageDataUrl(): string;
Get unmodified current image data url.
Returns
string
hideActivitySpinner()
hideActivitySpinner(): void;
Hide activity spinner.
Returns
void
Example
viewer.hideActivitySpinner();
hideSecondToolbar()
hideSecondToolbar(toolbarKey?): Promise<void>;
Hides the second toolbar. This method deactivates any active editor mode associated with the second toolbar and then hides the toolbar itself.
Parameters
toolbarKey?
Optional. The key identifying the specific second toolbar to hide. If provided, only hides the specified toolbar if it exists.
Returns
Promise<void>
A Promise that resolves once the second toolbar is successfully hidden.
Examples
// Hide the second toolbar
viewer.hideSecondToolbar();
// Hide a specific second toolbar by passing its key
viewer.hideSecondToolbar("page-tools");
newImage()
newImage(options?): Promise<any>;
Create new empty image.
Parameters
options?
Partial<Size> & OpenParameters
Optional. New image parameters.
Returns
Promise<any>
Example
await viewer.newImage({ width: 300, height: 300, fileName: "myImage.png" });
open()
open(file, openParameters?): Promise<any>;
Open Image document.
Parameters
file
string | URL | Uint8Array<ArrayBufferLike>
Image URL or it's binary data.
openParameters?
| OpenParameters
| ImageFormatCode
| ImageFormatName
Image format or image opening parameters object.
Returns
Promise<any>
Example
viewer.open("Images/HelloWorld.png");
openLocalFile()
openLocalFile(): void;
Show the file open dialog where the user can select the Image file.
Returns
void
Example
viewer.openLocalFile();
redo()
redo(): Promise<void>;
Redo changes.
Returns
Promise<void>
Example
if(viewer.hasRedo) {
viewer.redo();
}
removeKeyboardListener()
removeKeyboardListener(uniqueKey): void;
Remove window keyboard listener.
Parameters
uniqueKey
string
Listener key.
Returns
void
removeLayer()
removeLayer(layerOrIndex): void;
Remove and dispose image layer given by argument layerOrIndex.
Parameters
layerOrIndex
string | number | ImageLayer
Image layer or image layer index or image layer name.
Returns
void
removeLayers()
removeLayers(): void;
Remove and dispose all image layers.
Returns
void
removePlugin()
removePlugin(pluginId): void;
Removes a plugin instance from the DsImageViewer. This method remains available for internal and officially supported plugins only. Custom or third-party plugins are no longer supported starting from version 9.0.
Parameters
pluginId
| ImageViewerPluginReference
| PluginType
Plugin id or plugin instance.
Returns
void
Example
// ✅ Supported
viewer.removePlugin("ImageFiltersPlugin");
// ❌ Not supported
viewer.removePlugin("CustomPluginId");
removePlugins()
removePlugins(): void;
Remove all plug-ins.
Returns
void
Example
viewer.removePlugins();
resetCursor()
resetCursor(): void;
Resets the cursor to default style
Returns
void
Examples
// Reset cursor when operation completes
viewer.resetCursor();
// Reset cursor on mouse leave
viewerElement.addEventListener('mouseleave', () => {
viewer.resetCursor();
});
save()
save(options?, original?): void;
Saves the Image document loaded in the Viewer to the local disk.
Parameters
options?
string | SaveOptions
Optional Destination file name or the save options, including the destination file name and other settings.
original?
boolean
Optional Flag indicating whether to use the initial version of the image for save. Defaults to false.
Returns
void
Examples
// Example: Save the modified image without using specific options.
const viewer = DsImageViewer.findControl("#root");
viewer.save();
// Example: Save the modified image as "image.png".
const viewer = DsImageViewer.findControl("#root");
viewer.save({ fileName: "image.png" });
// Example: Download the original version of the image as "original_image.jpg".
const viewer = DsImageViewer.findControl("#root");
viewer.save({ fileName: "original_image.jpg", original: true });
// Example: Save the modified image in PNG format.
const viewer = DsImageViewer.findControl("#root");
viewer.save({ convertToFormat: "image/png" });
// Example: Save the modified image with a custom file name and in JPEG format.
const viewer = DsImageViewer.findControl("#root");
viewer.save({ fileName: "custom_name", convertToFormat: "image/jpeg" });
setCursor()
setCursor(cursorType): void;
Sets the cursor style for the image viewer
Parameters
cursorType
The cursor style to apply
Returns
void
Examples
// Set rotate cursor during image rotation
viewer.setCursor('rotate');
// Set resize cursor when hovering over edges
viewer.setCursor('nwse-resize');
See
GlobalCursorType for all available cursor options
setImageDataUrl()
setImageDataUrl(dataUrl): Promise<void>;
Modify current image data url.
Parameters
dataUrl
any
Returns
Promise<void>
showAbout()
showAbout(): void;
Show about dialog.
Returns
void
showActivitySpinner()
showActivitySpinner(container?): void;
Show activity spinner.
Parameters
container?
HTMLElement
Returns
void
Example
viewer.showActivitySpinner();
showMessage()
showMessage(
message,
details,
severity): void;
Shows the message for the user.
Parameters
message
string
Message title text
details
string
Additional details text, empty by default.
severity
"error" | "info" | "warn" | "debug"
Message severity, default "info".
Returns
void
showSecondToolbar()
showSecondToolbar(toolbarKey): Promise<void>;
Displays a second toolbar specified by the toolbarKey argument.
Parameters
toolbarKey
The key identifying the specific second toolbar to show.
Returns
Promise<void>
A Promise that resolves once the second toolbar is successfully displayed.
Example
// Show the page tools toolbar
viewer.showSecondToolbar("page-tools");
startAnimation()
startAnimation(): void;
Start GIF animation.
Returns
void
Example
DsImageViewer.findControl("#root").startAnimation();
stopAnimation()
stopAnimation(): void;
Stop GIF animation. *
Returns
void
Example
-
- DsImageViewer.findControl("#root").stopAnimation();
-
toggleAnimation()
toggleAnimation(): void;
Toggle GIF animation.
Returns
void
Example
DsImageViewer.findControl("#root").toggleAnimation();
toggleCursor()
toggleCursor(cursorType): void;
Toggles between specified cursor and default style
Parameters
cursorType
false | GlobalCursorType
Cursor style to apply, or false to reset
Returns
void
Examples
// Toggle grab cursor during drag operations
viewer.toggleCursor(isDragging ? 'grab' : false);
// Toggle zoom cursor based on modifier key
document.addEventListener('keydown', (e) => {
if (e.ctrlKey) {
viewer.toggleCursor('zoom-in');
}
});
triggerEvent()
triggerEvent(eventName, args?): void;
Trigger event.
Parameters
eventName
string
Embedded or custom event name.
args?
Record<string, unknown>
Arguments for event handler function.
Returns
void
Example
// Listen CustomEvent:
viewer.getEvent("CustomEvent").register(function(args) {
console.log(args);
});
// Trigger CustomEvent:
viewer.triggerEvent("CustomEvent", { arg1: 1, arg2: 2});
undo()
undo(): Promise<void>;
Undo changes.
Returns
Promise<void>
Example
if(viewer.hasUndo) {
viewer.undo();
}