Document Solutions Image Viewer
    Preparing search index...

    Class DsImageViewer

    Document Solutions Image Viewer is a fast JavaScript based client-side Image Viewer that runs in all major browsers.

    Note that DsImageViewer is the new name for GcImageViewer, with the same API.

    During this transition period we are publishing both versions, but it is recommended that you switch to using DsImageViewer when possible.

    const viewer = new DsImageViewer("#root");

    Hierarchy (View Summary)

    Implements

    Constructors

    Methods

    • Gets the viewer instance using the host element or host element selector.

      Parameters

      • selector: string | HTMLElement

        Root HTML element or its CSS selector

      Returns ImageViewerAPI | undefined

      Image Viewer instance if found

      const viewer = DsImageViewer.findControl("#root");

    • Call this method in order to apply changes in @see:toolbarLayout.

      Returns void

      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();

    • 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

      Returns boolean

      true if added successfully; otherwise false.

      // ✅ 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

    • Allows to configure the main toolbar layout.

      Parameters

      • pos: number | boolean | undefined

        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

      // Apply a custom layout to insert "zoomIn" and "zoomOut" buttons at position 2 for the "PaintTools" plugin.
      viewer.configurePluginMainToolbar(2, ["zoomIn", "zoomOut"]);

    • 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 PointLocation

    • Sets the cursor style for the image viewer

      Parameters

      Returns void

      // Set rotate cursor during image rotation
      viewer.setCursor('rotate');

      // Set resize cursor when hovering over edges
      viewer.setCursor('nwse-resize');

      GlobalCursorType for all available cursor options

    • Resets the cursor to default style

      Returns void

      // Reset cursor when operation completes
      viewer.resetCursor();

      // Reset cursor on mouse leave
      viewerElement.addEventListener('mouseleave', () => {
        viewer.resetCursor();
      });

    • Toggles between specified cursor and default style

      Parameters

      Returns void

      // 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');
        }
      });

    • Display confirmation dialog.

      Parameters

      • OptionalconfirmationText: any

        Confirmation text can be plain string or JSX.Element if you're using React.

      • Optionallevel: "error" | "info" | "warning"
      • Optionaltitle: string
      • Optionalbuttons: ConfirmButton[]

      Returns Promise<boolean | ConfirmButton>

      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
      }

    • Undo changes.

      Returns Promise<void>

      if(viewer.hasUndo) {
        viewer.undo();
      }

    • Redo changes.

      Returns Promise<void>

      if(viewer.hasRedo) {
        viewer.redo();
      }

    • Get event object.

      Parameters

      • eventName: string

        Embedded or custom event name.

      Returns EventFan

      viewer.getEvent("CustomEvent").register(function(args) {
        console.log(args);
      });

    • Trigger event.

      Parameters

      • eventName: string

        Embedded or custom event name.

      • Optionalargs: Record<string, unknown>

        Arguments for event handler function.

      Returns void

      // Listen CustomEvent:
      viewer.getEvent("CustomEvent").register(function(args) {
        console.log(args);
      });
      // Trigger CustomEvent:
      viewer.triggerEvent("CustomEvent", { arg1: 1, arg2: 2});

    • Displays a second toolbar specified by the toolbarKey argument.

      Parameters

      • toolbarKey: SecondToolbarType

        The key identifying the specific second toolbar to show.

      Returns Promise<void>

      A Promise that resolves once the second toolbar is successfully displayed.

      // Show the page tools toolbar
      viewer.showSecondToolbar("page-tools");

    • Hides the second toolbar. This method deactivates any active editor mode associated with the second toolbar and then hides the toolbar itself.

      Parameters

      • OptionaltoolbarKey: SecondToolbarType

        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.

      // Hide the second toolbar
      viewer.hideSecondToolbar();

      // Hide a specific second toolbar by passing its key
      viewer.hideSecondToolbar("page-tools");

    • Saves the Image document loaded in the Viewer to the local disk.

      Parameters

      • Optionaloptions: string | SaveOptions

        Optional Destination file name or the save options, including the destination file name and other settings.

      • Optionaloriginal: boolean

        Optional Flag indicating whether to use the initial version of the image for save. Defaults to false.

      Returns void

      // 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" });

    • 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

    Properties

    LicenseKey: string

    Gets or sets the license key.

    hasImage: boolean

    Indicates whether the viewer has opened the image.

     const hasImageFlag = viewer.hasImage;
    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.

    actualSize: Size

    Gets the actual display size of the active image, including the active zoom value.

    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.

    Standardized language key (e.g., 'en', 'ja').

    layers: ImageLayer[]

    Image layers. Used for painting.

    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.

    openParameters: OpenParameters | undefined

    The Open parameters that were used to open an image.

    undoStorage: UndoStorage

    Command based undo state storage.

    const isUndoInProgress = viewer.undoStorage.undoInProgress;
    hasUndo: boolean

    Gets a value indicating whether the image viewer can undo changes.

    if(viewer.hasUndo) {
      viewer.undo();
    }
    hasRedo: boolean

    Gets a value indicating whether the image viewer can redo changes.

    if(viewer.hasRedo) {
      viewer.redo();
    }
    undoIndex: number

    Gets current undo level index.

    alert("The current Undo level index is " + viewer.undoIndex);
    undoCount: number

    Gets total undo levels count.

    alert("Undo levels count is " + viewer.undoCount);
    version: string

    Returns the current version of the DS Image viewer.

    alert("The DsImageViewer version is " + viewer.version);
    framesCount: number

    Gets total frames count for the active image. Applicable for TIFF, ICO images.

    const viewer = new DsImageViewer('#root');
    viewer.onAfterOpen.register(function() {
      alert("The image opened. Total number of frames: " + viewer.framesCount);
    });
    viewer.open('Test.png');
    eventBus: EventBus

    Image viewer event bus.

    viewer.eventBus.on("after-open", function(args) {
      console.log("Image opened.", args);
    });
    viewer.open('Test.png');
    onAfterOpen: EventFan

    The event raised when the user changes the viewer theme.

    const viewer = new DsImageViewer('#root');
    viewer.onAfterOpen.register(function() {
      alert("The image opened.");
    });
    viewer.open('Test.png');
    onBeforeOpen: EventFan

    Occurs immediately before the image opens.

    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: EventFan

    The event indicating error.

    function handleError(args) {
        console.error(args);
    }
    const viewer = new DsImageViewer('#root');
    viewer.onError.register(handleError);
    viewer.open('Test.png');
    onImagePaint: EventFan

    The event raised when appearance image element changed.

    isAnimationStarted: boolean

    Gets a value indicating whether the image animation has started.

    // Toggle image animation:
    const viewer = DsImageViewer.findControl("#root");
    if(viewer.isAnimationStarted) {
      viewer.stopAnimation();
    } else {
      viewer.startAnimation();
    }
    options: Partial<ViewerOptions>

    Viewer options

    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'

    // Customize the toolbar layout:
    viewer.toolbarLayout.viewer.default = ["open", "$zoom", "$fullscreen", "save", "print", "about"];
    viewer.applyToolbarLayout();
    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.

    const viewer = new DsImageViewer('#root');
    viewer.frameIndex = 9;
    viewer.open('Test.ico');
    zoom: ZoomSettings

    Gets or sets the current zoom settings

    Constructors
    Methods
    Properties