# Class: HTMLSource

**`Experimental`** **`Advanced`**

A texture source backed by the experimental HTML-in-Canvas browser APIs. It renders a live
DOM [Element](https://developer.mozilla.org/docs/Web/API/Element) into a texture you can use anywhere a normal texture works: on a
[Sprite](scene.Sprite.html.md), as a [Texture](rendering.Texture.html.md) frame, in a mesh, and so on.

The element keeps its native browser behavior while it is rendered: forms stay editable,
links stay clickable, and CSS animations keep running. PixiJS just mirrors its pixels into
the GPU each time the browser repaints it.

The source resource must be a direct child of the renderer's `<canvas layoutsubtree>`
element. For an immutable, transferable copy that never repaints, use
[ElementImageSource](rendering.ElementImageSource.html.md) instead.

> [!NOTE]
> This relies on an experimental browser proposal and requires the HTML-in-Canvas API to be
> enabled; without it the texture uploader throws on first render. A generic HTML element
> passed to `Texture.from` resolves to an `HTMLSource` only as a last resort (it has the
> lowest texture-source priority); construct it explicitly when you need options or
> non-HTML elements such as SVG.

## Examples

```ts
import { Application, Sprite } from 'pixi.js';
import { HTMLSource } from 'pixi.js/html-source';

const app = new Application();

await app.init({ resizeTo: window });
document.body.appendChild(app.canvas);

// The element must be a direct child of the Pixi canvas.
const form = document.createElement('form');

form.innerHTML = '<input value="still editable" />';
app.canvas.appendChild(form);

// Render the live form as a sprite. It stays interactive in the browser.
const source = new HTMLSource({ resource: form });
const sprite = Sprite.from(source);

sprite.anchor.set(0.5);
sprite.position.set(app.screen.width / 2, app.screen.height / 2);
app.stage.addChild(sprite);
```

```ts
// Continuous animation: drive repaints yourself each frame.
const source = new HTMLSource({ resource: animatedDiv, autoRequestPaint: false });
const sprite = Sprite.from(source);

app.ticker.add(() => {
    sprite.rotation += 0.01;
    source.requestPaint(); // re-snapshot the DOM this frame
});
```

```ts
// Slice the rendered element into sub-textures (e.g. a "shatter" effect).
import { Rectangle, Texture } from 'pixi.js';

const pageSource = new HTMLSource({ resource: page });
const chunk = new Texture({
    source: pageSource,
    frame: new Rectangle(0, 0, 64, 64),
});
```

```ts
// Auto-detected: a generic HTML element passed to Texture.from resolves to an HTMLSource
// when no other built-in source claims it. Prefer the explicit form for options.
const sprite = Sprite.from(divAlreadyInTheCanvas);
```

## See

 - [HTMLSourceOptions](rendering.HTMLSourceOptions.html.md) For configuration options
 - [ElementImageSource](rendering.ElementImageSource.html.md) For an immutable snapshot instead of a live element
 - [Sprite](scene.Sprite.html.md) For displaying the source on screen
 - [Texture](rendering.Texture.html.md) For framing or slicing the source

## Extends

- [`TextureSource`](rendering.TextureSource.html.md)\<[`Element`](https://developer.mozilla.org/docs/Web/API/Element)\>

## Constructors

### Constructor

> **new HTMLSource**(`options`): `HTMLSource`

**`Experimental`**

#### Parameters

##### options

[`HTMLSourceOptions`](rendering.HTMLSourceOptions.html.md)

Options for creating the HTML source. `resource` is required.

#### Returns

`HTMLSource`

#### Example

```ts
const source = new HTMLSource({
    resource: domElement,   // a direct child of the Pixi canvas
    autoUpdate: true,       // track browser repaints (default)
    autoRequestPaint: true, // request one initial paint (default)
});
```

#### Overrides

[`TextureSource`](rendering.TextureSource.html.md).[`constructor`](rendering.TextureSource.html#constructor)

## Properties

### \_gcData?

> `optional` **\_gcData**: [`GCData`](rendering.GCData.html.md)

**`Experimental`**

GC tracking data, undefined if not being tracked

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`_gcData`](rendering.TextureSource.html#_gcdata)

***

### alphaMode

> **alphaMode**: [`ALPHA_MODES`](rendering.ALPHA_MODES.html.md)

**`Experimental`**

the alpha mode of the texture

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`alphaMode`](rendering.TextureSource.html#alphamode)

***

### antialias

> **antialias**: `boolean` = `false`

**`Experimental`**

Only really affects RenderTextures.
Should we use antialiasing for this texture. It will look better, but may impact performance as a
Blit operation will be required to resolve the texture.

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`antialias`](rendering.TextureSource.html#antialias)

***

### arrayLayerCount

> **arrayLayerCount**: `number` = `1`

**`Experimental`**

how many array layers this texture has (WebGPU depthOrArrayLayers)

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`arrayLayerCount`](rendering.TextureSource.html#arraylayercount)

***

### autoGarbageCollect

> **autoGarbageCollect**: `boolean`

**`Experimental`**

If true, the Garbage Collector will unload this texture if it is not used after a period of time

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`autoGarbageCollect`](rendering.TextureSource.html#autogarbagecollect)

***

### autoGenerateMipmaps

> **autoGenerateMipmaps**: `boolean` = `false`

**`Experimental`**

Should we auto generate mipmaps for this texture? This will automatically generate mipmaps
for this texture when uploading to the GPU. Mipmapped textures take up more memory, but
can look better when scaled down.

For performance reasons, it is recommended to NOT use this with RenderTextures, as they are often updated every frame.
If you do, make sure to call `updateMipmaps` after you update the texture.

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`autoGenerateMipmaps`](rendering.TextureSource.html#autogeneratemipmaps)

***

### canvas

> **canvas**: [`HTMLSourceCanvas`](rendering.HTMLSourceCanvas.html.md)

**`Experimental`**

Owning canvas used for `paint` events and [HTMLSource.requestPaint](#requestpaint). Set to `null`
once the source is destroyed.

***

### destroyed

> `readonly` **destroyed**: `boolean`

**`Experimental`**

Has the source been destroyed?

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`destroyed`](rendering.TextureSource.html#destroyed)

***

### dimension

> **dimension**: [`TEXTURE_DIMENSIONS`](rendering.TEXTURE_DIMENSIONS.html.md) = `'2d'`

**`Experimental`**

how many dimensions does this texture have? currently v8 only supports 2d

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`dimension`](rendering.TextureSource.html#dimension)

***

### format

> **format**: [`TEXTURE_FORMATS`](rendering.TEXTURE_FORMATS.html.md) = `'rgba8unorm'`

**`Experimental`**

the format that the texture data has

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`format`](rendering.TextureSource.html#format)

***

### height

> **height**: `number` = `1`

**`Experimental`**

the height of this texture source, accounting for resolution
eg pixelHeight 200, resolution 2, then height will be 100

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`height`](rendering.TextureSource.html#height)

***

### isPowerOfTwo

> **isPowerOfTwo**: `boolean`

**`Experimental`**

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`isPowerOfTwo`](rendering.TextureSource.html#ispoweroftwo)

***

### label

> **label**: `string`

**`Experimental`**

optional label, can be used for debugging

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`label`](rendering.TextureSource.html#label)

***

### mipLevelCount

> **mipLevelCount**: `number` = `1`

**`Experimental`**

The number of mip levels to generate for this texture.
this is overridden if autoGenerateMipmaps is true. it is read only!

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`mipLevelCount`](rendering.TextureSource.html#miplevelcount)

***

### pixelHeight

> **pixelHeight**: `number` = `1`

**`Experimental`**

the pixel height of this texture source. This is the REAL pure number, not accounting resolution

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`pixelHeight`](rendering.TextureSource.html#pixelheight)

***

### pixelWidth

> **pixelWidth**: `number` = `1`

**`Experimental`**

the pixel width of this texture source. This is the REAL pure number, not accounting resolution

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`pixelWidth`](rendering.TextureSource.html#pixelwidth)

***

### resource

> **resource**: [`Element`](https://developer.mozilla.org/docs/Web/API/Element)

**`Experimental`**

the resource that will be uploaded to the GPU. This is where we get our pixels from
eg an ImageBimt / Canvas / Video etc

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`resource`](rendering.TextureSource.html#resource)

***

### uid

> `readonly` **uid**: `number`

**`Experimental`**

unique id for this Texture source

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`uid`](rendering.TextureSource.html#uid)

***

### uploadMethodId

> **uploadMethodId**: `string` = `'html'`

**`Experimental`**

The upload method for this texture.

#### Overrides

`TextureSource.uploadMethodId`

***

### viewDimension

> **viewDimension**: [`TEXTURE_VIEW_DIMENSIONS`](rendering.TEXTURE_VIEW_DIMENSIONS.html.md) = `'2d'`

**`Experimental`**

how this texture is viewed/sampled by shaders (WebGPU view dimension)

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`viewDimension`](rendering.TextureSource.html#viewdimension)

***

### width

> **width**: `number` = `1`

**`Experimental`**

the width of this texture source, accounting for resolution
eg pixelWidth 200, resolution 2, then width will be 100

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`width`](rendering.TextureSource.html#width)

***

### defaultOptions

> `static` **defaultOptions**: [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype)\<[`HTMLSourceOptions`](rendering.HTMLSourceOptions.html.md)\>

**`Experimental`**

The default options applied to every HTMLSource, merged with the options passed
to the constructor.

#### Example

```ts
// Make every HTMLSource opt out of automatic repaint tracking by default.
HTMLSource.defaultOptions.autoUpdate = false;
```

#### Overrides

[`TextureSource`](rendering.TextureSource.html.md).[`defaultOptions`](rendering.TextureSource.html#defaultoptions)

***

### extension

> `static` **extension**: [`ExtensionMetadata`](extensions.ExtensionMetadata.html.md)

**`Experimental`**

Registers the source with the [extensions](extensions.extensions.html.md) system at the lowest texture-source
priority, so automatic detection only falls back to it when no other built-in source
claims the resource.

***

### from()

> `static` **from**: (`resource`) => [`TextureSource`](rendering.TextureSource.html.md)

**`Experimental`**

A helper function that creates a new TextureSource based on the resource you provide.

#### Parameters

##### resource

[`TextureResourceOrOptions`](rendering.TextureResourceOrOptions.html.md)

The resource to create the texture source from.

#### Returns

[`TextureSource`](rendering.TextureSource.html.md)

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`from`](rendering.TextureSource.html#from)

## Accessors

### addressMode

#### Get Signature

> **get** **addressMode**(): [`WRAP_MODE`](rendering.WRAP_MODE.html.md)

**`Experimental`**

setting this will set wrapModeU, wrapModeV and wrapModeW all at once!

##### Returns

[`WRAP_MODE`](rendering.WRAP_MODE.html.md)

#### Set Signature

> **set** **addressMode**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

[`WRAP_MODE`](rendering.WRAP_MODE.html.md)

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`addressMode`](rendering.TextureSource.html#addressmode)

***

### isReady

#### Get Signature

> **get** **isReady**(): `boolean`

**`Experimental`**

`true` once the owning canvas has produced an initial paint snapshot, so the texture has
real pixels. Non-auto-updating sources are ready immediately.

##### Example

```ts
const source = new HTMLSource({ resource: domElement });

if (!source.isReady)
{
    // The first paint has not landed yet — the texture is still blank.
}
```

##### Returns

`boolean`

***

### lodMaxClamp

#### Get Signature

> **get** **lodMaxClamp**(): `number`

**`Experimental`**

Specifies the minimum and maximum levels of detail, respectively, used internally when sampling a texture.

##### Returns

`number`

#### Set Signature

> **set** **lodMaxClamp**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`lodMaxClamp`](rendering.TextureSource.html#lodmaxclamp)

***

### lodMinClamp

#### Get Signature

> **get** **lodMinClamp**(): `number`

**`Experimental`**

Specifies the minimum and maximum levels of detail, respectively, used internally when sampling a texture.

##### Returns

`number`

#### Set Signature

> **set** **lodMinClamp**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`lodMinClamp`](rendering.TextureSource.html#lodminclamp)

***

### magFilter

#### Get Signature

> **get** **magFilter**(): [`SCALE_MODE`](rendering.SCALE_MODE.html.md)

**`Experimental`**

Specifies the sampling behavior when the sample footprint is smaller than or equal to one texel.

##### Returns

[`SCALE_MODE`](rendering.SCALE_MODE.html.md)

#### Set Signature

> **set** **magFilter**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

[`SCALE_MODE`](rendering.SCALE_MODE.html.md)

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`magFilter`](rendering.TextureSource.html#magfilter)

***

### maxAnisotropy

#### Get Signature

> **get** **maxAnisotropy**(): `number`

**`Experimental`**

##### Returns

`number`

#### Set Signature

> **set** **maxAnisotropy**(`value`): `void`

**`Experimental`**

Specifies the maximum anisotropy value clamp used by the sampler.

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`maxAnisotropy`](rendering.TextureSource.html#maxanisotropy)

***

### minFilter

#### Get Signature

> **get** **minFilter**(): [`SCALE_MODE`](rendering.SCALE_MODE.html.md)

**`Experimental`**

Specifies the sampling behavior when the sample footprint is larger than one texel.

##### Returns

[`SCALE_MODE`](rendering.SCALE_MODE.html.md)

#### Set Signature

> **set** **minFilter**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

[`SCALE_MODE`](rendering.SCALE_MODE.html.md)

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`minFilter`](rendering.TextureSource.html#minfilter)

***

### mipmapFilter

#### Get Signature

> **get** **mipmapFilter**(): [`SCALE_MODE`](rendering.SCALE_MODE.html.md)

**`Experimental`**

Specifies behavior for sampling between mipmap levels.

##### Returns

[`SCALE_MODE`](rendering.SCALE_MODE.html.md)

#### Set Signature

> **set** **mipmapFilter**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

[`SCALE_MODE`](rendering.SCALE_MODE.html.md)

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`mipmapFilter`](rendering.TextureSource.html#mipmapfilter)

***

### repeatMode

#### Get Signature

> **get** **repeatMode**(): [`WRAP_MODE`](rendering.WRAP_MODE.html.md)

**`Experimental`**

setting this will set wrapModeU, wrapModeV and wrapModeW all at once!

##### Returns

[`WRAP_MODE`](rendering.WRAP_MODE.html.md)

#### Set Signature

> **set** **repeatMode**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

[`WRAP_MODE`](rendering.WRAP_MODE.html.md)

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`repeatMode`](rendering.TextureSource.html#repeatmode)

***

### resolution

#### Get Signature

> **get** **resolution**(): `number`

**`Experimental`**

the resolution of the texture. Changing this number, will not change the number of pixels in the actual texture
but will the size of the texture when rendered.

changing the resolution of this texture to 2 for example will make it appear twice as small when rendered (as pixel
density will have increased)

##### Returns

`number`

#### Set Signature

> **set** **resolution**(`resolution`): `void`

**`Experimental`**

##### Parameters

###### resolution

`number`

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`resolution`](rendering.TextureSource.html#resolution)

***

### resourceHeight

#### Get Signature

> **get** **resourceHeight**(): `number`

**`Experimental`**

Height in real pixels (`offsetHeight`). Use [height](rendering.TextureSource.html#height) for CSS pixels.

##### Returns

`number`

#### Overrides

[`TextureSource`](rendering.TextureSource.html.md).[`resourceHeight`](rendering.TextureSource.html#resourceheight)

***

### resourceWidth

#### Get Signature

> **get** **resourceWidth**(): `number`

**`Experimental`**

Width in real pixels (`offsetWidth`). Use [width](rendering.TextureSource.html#width) for CSS pixels.

##### Returns

`number`

#### Overrides

[`TextureSource`](rendering.TextureSource.html.md).[`resourceWidth`](rendering.TextureSource.html#resourcewidth)

***

### scaleMode

#### Get Signature

> **get** **scaleMode**(): [`SCALE_MODE`](rendering.SCALE_MODE.html.md)

**`Experimental`**

setting this will set magFilter,minFilter and mipmapFilter all at once!

##### Returns

[`SCALE_MODE`](rendering.SCALE_MODE.html.md)

#### Set Signature

> **set** **scaleMode**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

[`SCALE_MODE`](rendering.SCALE_MODE.html.md)

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`scaleMode`](rendering.TextureSource.html#scalemode)

***

### source

#### Get Signature

> **get** **source**(): [`TextureSource`](rendering.TextureSource.html.md)

**`Experimental`**

returns itself

##### Returns

[`TextureSource`](rendering.TextureSource.html.md)

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`source`](rendering.TextureSource.html#source)

***

### style

#### Get Signature

> **get** **style**(): [`TextureStyle`](rendering.TextureStyle.html.md)

**`Experimental`**

the style of the texture

##### Returns

[`TextureStyle`](rendering.TextureStyle.html.md)

#### Set Signature

> **set** **style**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

[`TextureStyle`](rendering.TextureStyle.html.md)

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`style`](rendering.TextureSource.html#style)

***

### wrapMode

#### Get Signature

> **get** **wrapMode**(): [`WRAP_MODE`](rendering.WRAP_MODE.html.md)

**`Experimental`**

##### Returns

[`WRAP_MODE`](rendering.WRAP_MODE.html.md)

#### Set Signature

> **set** **wrapMode**(`value`): `void`

**`Experimental`**

##### Parameters

###### value

[`WRAP_MODE`](rendering.WRAP_MODE.html.md)

##### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`wrapMode`](rendering.TextureSource.html#wrapmode)

## Methods

### destroy()

> **destroy**(): `void`

**`Experimental`**

Detaches the `paint` listener from the owning canvas and destroys the underlying texture
source.

#### Returns

`void`

#### Example

```ts
const source = new HTMLSource({ resource: domElement });

source.destroy();
```

#### Overrides

[`TextureSource`](rendering.TextureSource.html.md).[`destroy`](rendering.TextureSource.html#destroy)

***

### requestPaint()

> **requestPaint**(): `boolean`

**`Experimental`**

Request a `paint` event from the owning canvas. Call this every frame to keep an animated
or frequently-changing element in sync with the rendered texture.

#### Returns

`boolean`

`true` if the request was made, `false` when the browser lacks the experimental
`requestPaint` API or there is no owning canvas.

#### Example

```ts
const source = new HTMLSource({ resource: clock, autoRequestPaint: false });

app.ticker.add(() => {
    clock.textContent = new Date().toLocaleTimeString();
    source.requestPaint();
});
```

***

### resize()

> **resize**(`width?`, `height?`, `resolution?`): `boolean`

**`Experimental`**

Resize the texture, this is handy if you want to use the texture as a render texture

#### Parameters

##### width?

`number`

the new width of the texture

##### height?

`number`

the new height of the texture

##### resolution?

`number`

the new resolution of the texture

#### Returns

`boolean`

- if the texture was resized

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`resize`](rendering.TextureSource.html#resize)

***

### unload()

> **unload**(): `void`

**`Experimental`**

This will unload the Texture source from the GPU. This will free up the GPU memory
As soon as it is required fore rendering, it will be re-uploaded.

#### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`unload`](rendering.TextureSource.html#unload)

***

### update()

> **update**(): `void`

**`Experimental`**

call this if you have modified the texture outside of the constructor

#### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`update`](rendering.TextureSource.html#update)

***

### updateMipmaps()

> **updateMipmaps**(): `void`

**`Experimental`**

Lets the renderer know that this texture has been updated and its mipmaps should be re-generated.
This is only important for RenderTexture instances, as standard Texture instances will have their
mipmaps generated on upload. You should call this method after you make any change to the texture

The reason for this is is can be quite expensive to update mipmaps for a texture. So by default,
We want you, the developer to specify when this action should happen.

Generally you don't want to have mipmaps generated on Render targets that are changed every frame,

#### Returns

`void`

#### Inherited from

[`TextureSource`](rendering.TextureSource.html.md).[`updateMipmaps`](rendering.TextureSource.html#updatemipmaps)

***

### test()

> `static` **test**(`resource`): `resource is Element`

**`Experimental`**

Tests whether a resource should be handled by `HTMLSource` during automatic source
detection (`Texture.from`, `TextureSource.from`). Deliberately strict: only generic HTML
elements pass. Image, video, and canvas elements are rejected because they have
dedicated, faster sources; snapshots are handled by [ElementImageSource](rendering.ElementImageSource.html.md).

#### Parameters

##### resource

`any`

The resource to test.

#### Returns

`resource is Element`

`true` if this source can handle the resource.

#### Overrides

[`TextureSource`](rendering.TextureSource.html.md).[`test`](rendering.TextureSource.html#test)
