The <spine-widget> tag allows you to place your Spine animations into a web page.

By default, the animation bounds are calculated using the given animation, or the setup pose if no animation is provided.
The bounds is centered and scaled to fit the parent container.
You can change the fit mode of your Spine animation using the fit attribute.

This is fit="fill". Default fit value is fit="contain".
If you want to preserve the original scale, you can use the fit="none". In combination with that, you can use the scale attribute to choose you desired scale.

Other fit modes are width, width, height, cover,and scaleDown.
If you want to manually size the Spine widget, specify the attributes width and height in pixels (without the px unit).

If you prefer you can style the component using the style attribute. There you have more styling options.
Mode origin center the animation world origin with the center of the HTML element.
You are responsible to scale the skeleton using this mode.

Move the origin by a percentage of the div width and height by using x-axis and y-axis respectively.
Use offset-x and offset-y to move you skeleton left or right by the pixel amount you specify.
You can virtually add a padding to the element container by using pad-left, pad-right, pad-top, pad-bottom.

As a value you can use a percentage of the width for left and right, and of the height for top and bottom.
You can customize the bounds, for example to focus on certain details of your animation.

The bounds-x, bounds-y, bounds-width and bounds-height allows to define custom bounds.

In this example we're zooming in into Celeste's face. You probably want to use clip in this case to avoid the skeleton overflow.
Give an identifier to your widget to get it by using the spine.getSpineWidget function. You can easily access the Skeleton and the AnimationState of your character, and use them as if you were using spine-webgl.

If you change animation, you can ask the widget to scale the skeleton based on the new animation.
Moving the div will move the skeleton origin.
Resizing the div will resize the skeleton in inside mode, but not in origin mode.
Interact with the example above dragging the div and resizing it
You can view the skeleton world origin (green), the root bone position (red), and the bounds rectangle and center (blue) by setting debug to true.
A loading spinner is shown during assets loading. Click the button below to simulate a 2 seconds loading:



If you do not want to show the loading spinner, set spinner="false".
Click the button below to toggle the spinner.
It's super easy to show your different skins and animations. Just make a table and use the skin and animation attributes.
If you have many atlas pages, for example one for each skin, and you want to show only some of the skins, pass to the pages the atlas pages you want to load as a comma concatenated list of indices.
Let's do the same thing above, but programmatically! Create two arrays, one for the skin and the other for the animations, and loop over them.

spine.createSpineWidget allows you to create a spine widget.

By default, assets are loaded immeaditely. You can postpone that by setting manual-start="false". Then add the widget to the dom using the asynchronous method appendTo. It's your responsibility to call start() on the widget. As usual, just wait on the loadingPromise to act on the skeleton or the state.
When the widget (or the parent element) enters in the viewport, the callback onScreenFunction is invoked.

By default, the callback does two things:
  • set onScreenAtLeastOnce to true when the widget enters the viewport the first time
  • if manual-start and on-screen-manual-start are set the widget start is invoked the first time the widget enters the viewport and the assets are loaded only in that moment.

The assets of the coin below are loaded only when the widget enters the viewport.

You can overwrite the onScreenFunction behaviour. For example, the raptor below changes animation everytime the widget enters the viewport.
If you want to load textures programmatically, you can just pass as pages to load an empty value liek this pages="".

In this way the skeleton and the atlas are loaded, but not the textures.
Then you can loads the textures whenever you want.
Widgets are not rendered while they are off screen.

The state and skeleton update, and the skeleton apply and the skeleton updateWorldTransform functions are not invoked when the widget is off screen.

If you want the update functions to be invoked in any case, set offscreen=update.
If you want all the functions to be invoked in any case, set offscreen=pose.

You can also overwrite the update function. Just assign a function to the update property of the widget. In that it's your responsibility to skip the update/apply. You can use the onScreen property for convinience.
If for some reason your skeleton bounds go outside the div, you can use the clip property to clip everything is outside the html container.

Be aware that this will break batching!
More examples for clip attribute.
If you use a spine widget in a element that has an ancestor that does not follow the webpage scroll, the effect might not be the desired one. You might encounter these problems:

1) For scrollable containers, the widget will be slightly slower to scroll than the html behind. The effect is more evident for lower refresh rate display.
2) For scrollable containers, the widget will overflow the container bounds until the widget html element container is visible
3) For fixed containers, the widget will scroll in a jerky way

In order to fix this behaviour, it is necessary to insert a dedicated spine-overlay webcomponent as a direct child of the container. Moreover, it is necessary to perform the following actions:

1) The scrollable container must have a transform css attribute. If it hasn't this attribute the spine-overlay will add it for you. If your scrollable container has already this css attribute, or if you prefer to add it by yourself (example: transform: translateZ(0);), set the scrollable-tweak-off to the spine-overlay.
2) The spine-overlay must have the scrollable attribute
3) The spine-overlay must have an overlay-id attribute. Choose the value you prefer.
4) Each spine-widget must have an overlay-id attribute. The same as the hosting spine-overlay.

Additionally, you can set overflow-top, overflow-bottom, overflow-left, overflow-right attributes to the spine-overlay in order to make the canvas bigger and prevent scrolling artifacts.

See the two examples below:
- Click the following button to open two elements with fixed positioned. The left one does not have a dedicated overlay and will scroll in a jerky way.
- Below there are two scrolling items. The left one does not have a dedicated overlay, it will lag on scroll and the widgets will overflow the container.
As a bonus item, you can move you skeleton around just by setting the isdraggable property to true.
If you need to determine the cursor position in the overlay world, you might find useful the following properties.
For spine-widget: For spine-overlay: You can use these property to interact with your widget. See the following examples where the owl eyes will follow the cursor, even if you drag the owls in another position. Exaggerate the movement by deselection the checkbox below.



This feature is experimental and might be removed in the future.
You can attach callback to your widget to react at pointer interactions. Just make it isinteractive.

You can attach a callback for interactions with the widget bounds or with slots. The available events are down, up, enter, leave, move, and drag.

In the following example, if the cursor enters the bounds, the jump animation is set, while the wave animation is set when the cursor leaves.
If you click on the head-base slot (the face), you can change the normal and dark tint with the colors selected in the two following selectors.
  • Tint normal:
  • Tint black: