artboard-deluxe

Appearance

artboard-deluxe / Artboard

Artboard ​

Artboard = object

Defined in: types/index.ts:446

The artboard instance.

Properties ​

options ​

options: Options

Defined in: types/index.ts:964

The artboard options.

Methods ​

addPlugin() ​

addPlugin<T>(plugin): T extends ArtboardPluginDefinition<O, R> ? ArtboardPluginInstance<O, R> : never

Defined in: types/index.ts:464

Add a plugin.

Use this method if you conditionally need to add or remove plugins.

Type Parameters ​

T ​

T extends ArtboardPluginDefinition<any, any>

Parameters ​

plugin ​

T

The plugin to add.

Returns ​

T extends ArtboardPluginDefinition<O, R> ? ArtboardPluginInstance<O, R> : never

Example ​

typescript
import { createArtboard, mouse } from 'artboard-deluxe'

const artboard = createArtboard(document.body)
const mousePlugin = mouse()
artboard.addPlugin(mousePlugin)

animateOrJumpBy() ​

animateOrJumpBy(providedX?, providedY?, options?): void

Defined in: types/index.ts:686

Animate or jump by the given offset.

If there is an animation running currently and it's last animation frame timestamp is less than 300ms ago, the animation will be stopped and the offset applied immediately.

Parameters ​

providedX? ​

How much pixels on the X axis to jump.

null | number

providedY? ​

How much pixels on the y axis to jump.

null | number

options? ​

AnimationOptions

The animation options.

Returns ​

void

animateOrJumpTo() ​

animateOrJumpTo(providedX?, providedY?, options?): void

Defined in: types/index.ts:701

Animate or scroll to the given offset.

If there is an animation running currently and it's last animation frame timestamp is less than 300ms ago, the animation will be stopped and the offset applied immediately.

Parameters ​

providedX? ​

The new offset on the x axis.

null | number

providedY? ​

The new offset on the y axis.

null | number

options? ​

AnimationOptions

The animation options.

Returns ​

void

animateTo() ​

animateTo(key, x, y, targetScale?, options?): void

Defined in: types/index.ts:653

Animate to the given state.

If an animation is currently running, it will be overriden. If momentum scrolling is currently applied, it will be stopped.

Parameters ​

key ​

string

The name of the animation.

x ​

number

The target x offset.

y ​

number

The target y offset.

targetScale? ​

number

The target scale.

options? ​

The animation options.

null | AnimationOptions

Returns ​

void

animateToBoundary() ​

animateToBoundary(): void

Defined in: types/index.ts:590

Starts an animation if the current offset and scale of the artboard is outside the possible boundaries.

Returns ​

void

calculateScaleAroundPoint() ​

calculateScaleAroundPoint(pageX, pageY, targetScale, providedOffset?, providedScale?): Coord & object

Defined in: types/index.ts:860

Scales around the given point and returns what the offset should be so that the point remains centered.

Parameters ​

pageX ​

number

The x coordinate relative to the page.

pageY ​

number

The y coordinate relative to the page.

targetScale ​

number

The target scale.

providedOffset? ​

Coord

providedScale? ​

number

Returns ​

Coord & object

cancelAnimation() ​

cancelAnimation(): void

Defined in: types/index.ts:836

Cancels the current animation.

Returns ​

void

destroy() ​

destroy(): void

Defined in: types/index.ts:584

Destroys the artboard instance, removes all event listeners, plugins and observers.

Returns ​

void

getAnimation() ​

getAnimation(): null | ArtboardAnimation

Defined in: types/index.ts:1027

Get the currently running animation.

Returns ​

null | ArtboardAnimation

The animation if it exists.

getArtboardSize() ​

getArtboardSize(): null | Size

Defined in: types/index.ts:668

Returns the size of the artboard.

When using "infinite mode" (without any artboard size) this value will be null.

Returns ​

null | Size

The artboard size.

getBoundaries() ​

getBoundaries(providedTargetScale?): Boundaries

Defined in: types/index.ts:1002

Get the current boundaries.

Parameters ​

providedTargetScale? ​

number

Calculate the boundaries if the given scale were applied.

Returns ​

Boundaries

The boundaries.

getCenterX() ​

getCenterX(targetScale?): number

Defined in: types/index.ts:639

Returns the x offset that perfectly centers the artboard within the possible bounds.

If the getBlockingRects option is provided, the method will also take blocking rects into account, if possible.

Parameters ​

targetScale? ​

number

The target scale for which to calculate the offset.

Returns ​

number

The x offset.

getFinalOffset() ​

getFinalOffset(): Coord

Defined in: types/index.ts:517

Get the final offset. If there is currently an animation, the method will return the target offset of the animation.

Returns ​

Coord

The offset.

getFinalScale() ​

getFinalScale(): number

Defined in: types/index.ts:503

If there is an animation running, it returns the target scale of the animation. Else the current applied scale is returned.

Returns ​

number

The finale scale of the artboard.

getInteraction() ​

getInteraction(): Interaction

Defined in: types/index.ts:916

Returns the current artboard interaction.

Returns ​

Interaction

The current interaction.

getMomentum() ​

getMomentum(): null | Coord

Defined in: types/index.ts:930

Get the current velocity.

Returns ​

null | Coord

The velocity.

getOffset() ​

getOffset(): Coord

Defined in: types/index.ts:510

Get the current applied offset of the artboard.

Returns ​

Coord

The offset.

getRootElement() ​

getRootElement(): HTMLElement

Defined in: types/index.ts:909

Returns the root element.

Returns ​

HTMLElement

The root element.

getRootSize() ​

getRootSize(): Size

Defined in: types/index.ts:675

Returns the size of the root element.

Returns ​

Size

The size of the root element.

getScale() ​

getScale(): number

Defined in: types/index.ts:495

Get the current applied scale of the artboard.

Returns ​

number

The current applied scale of the artboard.

getScaleTarget() ​

getScaleTarget(): null | ScaleTarget

Defined in: types/index.ts:1011

Get the current target scale.

Returns null when there is no target scale.

Returns ​

null | ScaleTarget

The target scale.

getTouchDirection() ​

getTouchDirection(): Direction

Defined in: types/index.ts:952

Get the current touch direction.

Returns ​

Direction

The touch direction.

loop() ​

loop(currentTime): ArtboardLoopContext

Defined in: types/index.ts:626

The main animation handler.

This method should be called from within a requestAnimationFrame callback. The method updates the internal state, applies momentum scrolling and animations.

The method returns a snapshot of the state at the time of the animation frame. For the best experience you should use these values as the "source of truth", for example when using a canvas for rendering.

Parameters ​

currentTime ​

number

The current time.

Returns ​

ArtboardLoopContext

The loop context that contains a snapshot of the state that is applied.

Example ​

typescript
import { createArtboard, dom } from 'artboard-deluxe'

const artboard = createArtboard(
  document.body,
  [
    dom(document.getElementById('artboard')))
  ]
)

function loop(timestamp: number) {
  artboard.loop(timestamp)
  window.requestAnimationFrame(loop)
}

loop()

observeSizeChange() ​

observeSizeChange<T>(element, cb): ObserverSizeChangeContext

Defined in: types/index.ts:899

Observe the size of the given element.

Type Parameters ​

T ​

T extends HTMLElement = HTMLElement

Parameters ​

element ​

T

The element to observe.

cb ​

ObserverSizeChangeCallback<T>

Returns ​

ObserverSizeChangeContext

removePlugin() ​

removePlugin(plugin): void

Defined in: types/index.ts:488

Removes a previously added plugin.

Parameters ​

plugin ​

ArtboardPluginInstance

The plugin to remove. Must be the same instance that has been added using addPlugin.

Returns ​

void

Example ​

typescript
import { createArtboard, clickZoom } from 'artboard-deluxe'

const artboard = createArtboard(document.body)
const plugin = clickZoom()
artboard.addPlugin(plugin)

function disableClickZoom() {
  artboard.removePlugin(plugin)
}

resetZoom() ​

resetZoom(options?): void

Defined in: types/index.ts:796

Reset zoom and center artboard on the x axis.

Parameters ​

options? ​

AnimationOptions

The animation options.

Returns ​

void

scaleAroundPoint() ​

scaleAroundPoint(pageX, pageY, targetScale, animation?): void

Defined in: types/index.ts:846

Scale the artboard around the given point.

Parameters ​

pageX ​

number

The x coordinate relative to the page.

pageY ​

number

The y coordinate relative to the page.

targetScale ​

number

The target scale.

animation? ​

If provided, the scale is animated.

boolean | AnimationOptions

Returns ​

void

scaleToFit() ​

scaleToFit(options?): void

Defined in: types/index.ts:789

Scale the artboard so it fits within the height of the root element.

Parameters ​

options? ​

AnimationOptions

Animation options.

Returns ​

void

scrollDown() ​

scrollDown(amount?, options?): void

Defined in: types/index.ts:754

Scroll down one step.

Parameters ​

amount? ​

number

options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollElementIntoView() ​

scrollElementIntoView(targetEl, options?): void

Defined in: types/index.ts:991

Scrolls the given element into view.

Only elements that are either a direct child of the root element or elements that are anchored to the artboard's location can be scrolled into view.

Parameters ​

targetEl ​

HTMLElement

The element to scroll into view.

options? ​

ArtboardScrollIntoViewOptions

Options for the scroll behaviour.

Returns ​

void

scrollIntoView() ​

scrollIntoView(targetRect, options?): void

Defined in: types/index.ts:881

Scrolls the given rectangle into view.

The rectangle's coordinates and sizes should be relative to the artboard, not the result of getBoundingClientRect(). For example, if the artboard is 1000x1000 big and it contains a 500x500 rectangle that is centered horizontally with a 50px margin on top, the value for targetRect would be: { x: 250 // Because (1000 - 500) / 2 = 250, y: 50, width: 500, height: 500, }

Parameters ​

targetRect ​

Rectangle

The rectangle to scroll into view. The coordinates and size of the rectangle should be uncaled and relative to the artboard.

options? ​

ArtboardScrollIntoViewOptions

Options for the scroll behaviour and animation.

Returns ​

void

scrollLeft() ​

scrollLeft(amount?, options?): void

Defined in: types/index.ts:761

Scroll left one step.

Parameters ​

amount? ​

number

options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollPageDown() ​

scrollPageDown(options?): void

Defined in: types/index.ts:726

Scroll down by one page.

Parameters ​

options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollPageLeft() ​

scrollPageLeft(options?): void

Defined in: types/index.ts:733

Scroll left by one page.

Parameters ​

options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollPageRight() ​

scrollPageRight(options?): void

Defined in: types/index.ts:740

Scroll right by one page.

Parameters ​

options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollPageUp() ​

Call Signature ​

scrollPageUp(options?): void

Defined in: types/index.ts:712

Scroll one page up.

Parameters ​
options? ​

AnimationOptions

The animation options.

Returns ​

void

Call Signature ​

scrollPageUp(options?): void

Defined in: types/index.ts:719

Scroll up by one page.

Parameters ​
options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollRight() ​

scrollRight(amount?, options?): void

Defined in: types/index.ts:768

Scroll right one step.

Parameters ​

amount? ​

number

options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollToEnd() ​

scrollToEnd(options?): void

Defined in: types/index.ts:782

Scroll to the end of the artboard.

Parameters ​

options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollToTop() ​

scrollToTop(options?): void

Defined in: types/index.ts:775

Scroll to the top of the artboard.

Parameters ​

options? ​

AnimationOptions

The animation options.

Returns ​

void

scrollUp() ​

scrollUp(amount?, options?): void

Defined in: types/index.ts:747

Scroll up one step.

Parameters ​

amount? ​

number

options? ​

AnimationOptions

The animation options.

Returns ​

void

setArtboardSize() ​

setArtboardSize(width, height): void

Defined in: types/index.ts:892

Set the artboard size.

When using the dom plugin, the artboard size is already set and updated automatically. Without the plugin (e.g. when using a canvas) it's expected to set the size manually.

Parameters ​

width ​

number

height ​

number

Returns ​

void

setDirectionOffset() ​

setDirectionOffset(x, y): void

Defined in: types/index.ts:981

Updates the offset based on the current touchDirection.

For example, if the current touchDirection is 'vertical', then only the Y offset is updated.

Parameters ​

x ​

number

The new x offset.

y ​

number

The new y offset.

Returns ​

void

setInteraction() ​

setInteraction(interaction?): void

Defined in: types/index.ts:923

Set the current interaction.

Parameters ​

interaction? ​

Interaction

The new interaction.

Returns ​

void

setMomentum() ​

Call Signature ​

setMomentum(x, y, deceleration?): void

Defined in: types/index.ts:940

Update the current velocity.

If an argument is null, the current velocity value for that axis is kept.

Parameters ​
x ​

number

The velocity on the x axis.

y ​

number

The velocity on the y axis.

deceleration? ​

number

Returns ​

void

Call Signature ​

setMomentum(): void

Defined in: types/index.ts:945

Stop momentum.

Returns ​

void

setOffset() ​

setOffset(providedX?, providedY?, immediate?): void

Defined in: types/index.ts:827

Set the offset.

Parameters ​

providedX? ​

The new x offset.

null | number

providedY? ​

The new y offset.

null | number

immediate? ​

boolean

If set the offset is applied immediately.

Returns ​

void

setOption() ​

setOption<T>(key, value): void

Defined in: types/index.ts:576

Update a single option.

Type Parameters ​

T ​

T extends keyof ArtboardOptions

Parameters ​

key ​

T

The name of the option to set.

value ​

ArtboardOptions[T]

The value of the option to set.

Returns ​

void

Example ​

Update the minScale option when the viewport changes.

typescript
import { createArtboard } from 'artboard-deluxe'

function getMinScale() {
  const isMobile = window.innerWidth < 768
  return isMobile ? 1 : 0.1
}

const artboard = createArtboard(document.body, [], {
  minScale: getMinScale(),
})

function onViewportChange() {
  artboard.setOption('minScale', getMinScale())
}

setOptions() ​

setOptions(options): void

Defined in: types/index.ts:548

Update all options.

Note that this will reset option properties back to defaults if they are missing from the provided options.

Parameters ​

options ​

ArtboardOptions

The full options to update.

Returns ​

void

Example ​

typescript
import { createArtboard, type ArtboardOptions } from 'artboard-deluxe'

function getOptions(): ArtboardOptions {
  const isMobile = window.innerWidth < 768
  const minScale = isMobile ? 1 : 0.1
  const maxScale = isMobile ? 5 : 10
  return {
    minScale,
    maxScale
  }
}

const artboard = createArtboard(document.body, [], getOptions())

function updateOptions() {
  artboard.setOptions(getOptions())
}

setScale() ​

setScale(newScale, immediate?): void

Defined in: types/index.ts:804

Set the scale of the artboard.

Parameters ​

newScale ​

number

The new scale to set.

immediate? ​

boolean

If true, the scale is applied immediately.

Returns ​

void

setScaleTarget() ​

setScaleTarget(x, y, scale): void

Defined in: types/index.ts:1020

Set the scale target.

Parameters ​

x ​

number

The target x offset.

y ​

number

The target y offset.

scale ​

number

The target scale.

Returns ​

void

setTouchDirection() ​

setTouchDirection(direction?): void

Defined in: types/index.ts:959

Set the current touch direction.

Parameters ​

direction? ​

Direction

The new touch direction. Defaults to 'none'.

Returns ​

void

startMomentum() ​

startMomentum(velocity?): void

Defined in: types/index.ts:971

Apply the given momentum.

Parameters ​

velocity? ​

Coord

The momentum to apply. If undefined, the velocity is reset and no momentum scrolling is applied.

Returns ​

void

wasMomentumScrolling() ​

wasMomentumScrolling(): boolean

Defined in: types/index.ts:1036

Determine whether the interaction before the current was momentum scrolling.

This is used by plugins such as the mouse() plugin to prevent clicking on an element of the artboard if the user was previously momentum scrolling and clicking to stop the animation.

Returns ​

boolean

True if the previous interaction was momentum scrolling.

zoomIn() ​

zoomIn(delta?): void

Defined in: types/index.ts:811

Zoom in the artboard by the given amount.

Parameters ​

delta? ​

number

The amount to zoom in.

Returns ​

void

zoomOut() ​

zoomOut(delta?): void

Defined in: types/index.ts:818

Zoom out the artboard by the given amount.

Parameters ​

delta? ​

number

The amount to zoom out.

Returns ​

void