Watermark Configuration Options

Basic Configuration

width

• Type: number
• Default: 300
• Description: Unit width for a single watermark element.

height

• Type: number
• Default: 300
• Description: Unit height for a single watermark element.

rotate

• Type: number
• Default: 45
• Description: Rotation angle of the watermark in degrees.

layout

• Type: LayoutType ('default' | 'grid')
• Default: 'default'
• Description: Controls the arrangement of watermark elements
• Available Values:

  • 'default' (Default mode)

    • Basic layout with minimal configuration
    • Suitable for simple use cases

  • 'grid' (Grid layout)

    • Arranges watermarks in a matrix grid pattern
    • gridLayoutOptions is optional and defaults to a 1 × 1 grid
    • Typical use case: Generating patterned watermark backgrounds

gridLayoutOptions

• Type: GridLayoutOptions | undefined
• Default: undefined
• Description: Custom options for grid-based layout configuration.
• Properties:
  • cols: Number of columns (default: 1)
  • rows: Number of rows (default: 1)
  • gap: Spacing as [horizontal, vertical] (default: [0, 0])
  • matrix: 2D matrix controlling visibility per grid cell (default: all 1s)
  • backgroundImage: Optional background image drawn across the grid; provide both width and height when using it
  • width: Optional custom total width (overrides cols/gap calculation)
  • height: Optional custom total height (overrides rows/gap calculation)
• Note: For Watermark and BlindWatermark, custom grid width and height change the generated grid canvas, while the CSS background size is still calculated from the unit size, rows, columns, and gaps.

auxiliaryLine

• Type: boolean
• Default: false
• Description: Whether to display auxiliary guidelines for positioning.

Positioning & Movement

translatePlacement

• Type: TranslatePlacementType
• Default: 'middle'
• Available Values:
  • 'top': Top center
  • 'top-start': Top left
  • 'top-end': Top right
  • 'bottom': Bottom center
  • 'bottom-start': Bottom left
  • 'bottom-end': Bottom right
  • 'left': Middle left
  • 'right': Middle right
  • 'middle': Center (default)
• Description:
  • Determines the base position for watermark placement and rotation transformation
  • Affects both the initial position and gradient calculations when using advanced styles
  • Automatically adjusts text alignment and baseline when not explicitly set
  • Coordinates with translateX and translateY for precise positioning
• Note:
  • When combined with rotation, the placement becomes the rotation center point
  • For text watermarks, this also affects text baseline calculation

translateX

• Type: number | undefined
• Default: Auto-calculated (based on translatePlacement and width)
• Description:
  • Horizontal offset (in pixels)
  • Positive value → Right movement | Negative value ← Left movement
  • Serves as X-coordinate for rotation pivot point
  • Affects calculation of linear/radial gradient start points

translateY

• Type: number | undefined
• Default: Auto-calculated (based on translatePlacement and height)
• Description:
  • Vertical offset (in pixels)
  • Positive value ↓ Downward movement | Negative value ↑ Upward movement
  • Serves as Y-coordinate for rotation pivot point
  • Affects automatic calculation of text baseline (textBaseline)
• Note: Custom coordinates require both translateX and translateY. If a non-middle translatePlacement is also explicitly provided, that placement takes precedence.

movable (animation)

• Type: boolean
• Default: false
• Description:
  When enabled, CSS animations change the watermark's background position. The behavior differs based on backgroundRepeat:
  • repeat: 2D background-position animation (200s duration)
  • repeat-x: Vertical background-position animation (random 2-8s duration)
  • repeat-y: Horizontal background-position animation (random 2-4s duration)
  • no-repeat: Combined horizontal and vertical background-position animation
• Live Examples:
  • StackBlitz
  • Demo
• Mechanism:
  • Implemented via CSS animation with randomized durations
  • Uses alternate direction for ping-pong effect
  • Durations use the ranges listed above for each backgroundRepeat value

zIndex

• Type: number
• Default: 2147483647
• Description: CSS z-index property for layering control.

parent

• Type: Element | string
• Default: 'body'
• Description: Container element for the watermark (selector or DOM element).

Content Configuration

contentType

• Type: ContentTypeType ('text' | 'image' | 'multi-line-text' | 'rich-text')
• Default: 'text'
• Available Values:
  • 'text': Simple text watermark
  • 'image': Image watermark
  • 'multi-line-text': Multi-line text watermark
  • 'rich-text': Formatted rich text watermark
• Description: Type of content to display as watermark.

content

• Type: string
• Default: 'hello watermark-js-plus'
• Description: Text or HTML used by text, multi-line-text, and rich-text modes. Image mode uses the separate image option.

textType

• Type: TextType ('fill' | 'stroke')
• Default: 'fill'
• Available Values: 'fill' | 'stroke'
• Description: Rendering method for text content.

Text Styling

fontSize

• Type: string
• Default: '20px'
• Description: Font size for text content.

fontFamily

• Type: string
• Default: 'sans-serif'
• Description: Font family for text content.

fontStyle

• Type: string
• Default: ''
• Description: Font style (e.g., 'italic').

fontVariant

• Type: string
• Default: ''
• Description: Font variant (e.g., 'small-caps').

fontWeight

• Type: string
• Default: 'normal'
• Description: Font weight (e.g., 'bold').

fontColor

• Type: string
• Default: '#000'
• Description: Text color.

textAlign

• Type: TextAlignType | undefined
• Default: Auto-calculated from translatePlacement ('center' for the default middle placement, or 'left' when both custom coordinates are used)
• Available Values: 'center', 'end', 'left', 'right', 'start'
• Description: Horizontal text alignment.

textBaseline

• Type: TextBaselineType | undefined
• Default: Auto-calculated from translatePlacement ('middle' for the default middle placement, or 'top' when both custom coordinates are used)
• Available Values:
  • 'top', 'bottom', 'middle'
  • 'alphabetic', 'hanging', 'ideographic'
• Description: Vertical text alignment baseline.

lineHeight

• Type: number
• Default: 30
• Description: Line height for multi-line text.

textRowMaxWidth

• Type: number | undefined
• Default: The configured width
• Description: Canvas text maxWidth; it is also the wrapping threshold for multi-line text.

letterSpacing

• Type: string
• Default: '0px'
• Description: Spacing between characters.

wordSpacing

• Type: string
• Default: '0px'
• Description: Spacing between words.

Image Configuration

image

• Type: string | undefined
• Default: undefined
• Description: URL of the image to use as watermark when contentType = 'image'. It is loaded with crossOrigin="anonymous", so remote servers must allow CORS.

imageWidth

• Type: number
• Default: 0
• Description: Display width. When both image dimensions are 0, the natural size is used; when only imageHeight is set, width is calculated from the original aspect ratio.

imageHeight

• Type: number
• Default: 0
• Description: Display height. When both image dimensions are 0, the natural size is used; when only imageWidth is set, height is calculated from the original aspect ratio.

Rich Text Configuration

richTextWidth

• Type: number | undefined
• Default: Measured rich-text content width, falling back to width
• Description: Width constraint for rich text content.

richTextHeight

• Type: number | undefined
• Default: Measured rich-text content height, falling back to height
• Description: Height constraint for rich text content.

Visual Effects

globalAlpha

• Type: number
• Default: 0.5
• Description: Overall transparency of the watermark (0.0 to 1.0).

filter

• Type: string
• Default: 'none'
• Description: Applies CSS filter effects similar to those available for CSS. The value is a string containing one or more of the following filter functions.
  • url(): Applies an SVG filter defined in an external resource (e.g., url(#custom-filter))
  • blur(<length>): Applies a Gaussian blur (e.g., blur(5px))
  • brightness(<percentage>): Adjusts brightness (e.g., brightness(150%))
  • contrast(<percentage>): Adjusts contrast (e.g., contrast(75%))
  • drop-shadow(<offset-x> <offset-y> <blur-radius> <color>): Applies a drop shadow (e.g., drop-shadow(4px 4px 8px blue))
  • grayscale(<percentage>): Converts to grayscale (e.g., grayscale(100%))
  • hue-rotate(<angle>): Applies hue rotation (e.g., hue-rotate(90deg))
  • invert(<percentage>): Inverts colors (e.g., invert(50%))
  • opacity(<percentage>): Adjusts opacity (e.g., opacity(25%))
  • saturate(<percentage>): Adjusts saturation (e.g., saturate(200%))
  • sepia(<percentage>): Applies sepia tone (e.g., sepia(80%))

Multiple filters can be combined by space-separating them (e.g., brightness(120%) contrast(110%)). The value 'none' indicates no filter effect.

shadowStyle

• Type: Partial<CanvasShadowStyles> | undefined
• Default: undefined
• Properties:
  • shadowColor: string
    Shadow color (supports all CSS color formats)
  • shadowBlur: number
    Blur level (in pixels, 0 = no blur)
  • shadowOffsetX: number
    Horizontal offset (in pixels, positive = right)
  • shadowOffsetY: number
    Vertical offset (in pixels, positive = down)
• Description: Adds standard Canvas shadow effects with features:
  • Supports transparency (alpha channel)
  • Offsets are unaffected by rotate/translate
  • Combines multiplicatively with globalAlpha
• Note:
  • Requires shadowColor to be set to take effect
  • Blur calculations may impact rendering performance
  • May appear subtle at low opacity (globalAlpha < 0.3)

advancedStyle

• Type: AdvancedStyleType | undefined
• Default: undefined
• Properties:
  • type: 'linear' | 'radial' | 'conic' | 'pattern'
    Gradient type (linear/radial/conic/pattern)
  • params: Configuration object
    • linear: { x0, y0, x1, y1 }
      Start/end coordinates for linear gradient
    • radial: { x0, y0, r0, x1, y1, r1 }
      Circle parameters for radial gradient
    • conic: { startAngle, x, y }
      Starting angle and center point for conic gradient
    • pattern: { image, repetition }
      Pattern fill settings
  • colorStops: Array<{ offset: number, color: string }>
    Color stop positions and values
• Description: Enables advanced fill styles that override default fontColor. Supports:
  • All CSS gradient types (auto-adapted to Canvas coordinates)
  • Image pattern fills
  • Smart coordinate positioning (auto-adjusts gradient points based on translatePlacement)
• Note:
  • Works with textType (applies to both fillStyle and strokeStyle)
  • Requires preloaded images for pattern type

backgroundPosition

• Type: string
• Default: '0 0'
• Description: CSS background-position property.

backgroundRepeat

• Type: string
• Default: 'repeat'
• Description: CSS background-repeat property.

Behavior & Security

mode

• Type: CreateWatermarkModeType ('default' | 'blind')
• Default: 'default'
• Available Values:
  • 'default': Standard visible watermark mode (normal transparency)
  • 'blind': Blind watermark mode identifier
• Description: Identifies the intended watermark mode. In a regular Watermark, setting this option to 'blind' does not change opacity by itself. BlindWatermark enforces mode: 'blind' and globalAlpha: 0.005.

mutationObserve

• Type: boolean
• Default: true
• Description: Whether to observe relevant attribute, child, and text changes within the watermark, plus direct removal from its parent, and recreate it when detected.

monitorProtection

• Type: boolean
• Default: false
• Description: Enable protection against MutationObserver tampering.
• Important: Once enabled, this protection cannot be disabled.

Callbacks

extraDrawFunc

• Type: Function | undefined
• Default: undefined
• Description: Additional drawing operations callback.

onSuccess

• Type: Function
• Default: () => {}
• Description: Called after the first successful creation. Redraws do not call it again; creating after destroy() does.

onBeforeDestroy

• Type: Function
• Default: () => {}
• Description: Called before watermark removal.

onDestroyed

• Type: Function
• Default: () => {}
• Description: Called after watermark removal.

onObserveError

• Type: Function
• Default: () => {}
• Description: Called when mutation observation fails.

ImageWatermark-only Configuration

dom

• Type: HTMLImageElement
• Required: Required when calling ImageWatermark.create()
• Description: Target image element. Its src is replaced with the generated watermarked PNG Data URL, and destroy() restores the original src.

crossOrigin

• Type: boolean | undefined
• Default: undefined
• Description: When truthy, sets the target image element's crossOrigin attribute to 'anonymous'. For a cross-origin image, the server must return compatible CORS headers for Canvas export.