Skip to main content

<pc-button>

The <pc-button> tag is used to define a button component, which makes an element respond to pointer input with visual transitions.

Usage
  • It must be a direct child of a <pc-entity>.
  • The entity must also have a <pc-element> (typically type="image") with the use-input attribute set, so the button can receive pointer input.

Attributes​

AttributeTypeDefaultDescription
activeBoolean"true"Whether the button responds to input
enabledBoolean"true"Enabled state of the component
fade-durationNumber"0"Duration in milliseconds over which tint transitions are applied
hit-paddingVector4"0 0 0 0"Expands the button's hit area as left bottom right top
hover-sprite-assetString-Sprite <pc-asset> id shown on hover (sprite transition mode)
hover-sprite-frameNumber"0"Frame of the hover sprite
hover-tintColor"1 1 1 1"Tint applied to the image entity on hover (tint transition mode)
imageString-Reference (CSS selector, element id, or entity name) to the <pc-entity> whose image element shows transitions. Defaults to the button's own entity — inside a <pc-model> that is the model's host, so name a UI entity explicitly there
inactive-sprite-assetString-Sprite <pc-asset> id shown when inactive (sprite transition mode)
inactive-sprite-frameNumber"0"Frame of the inactive sprite
inactive-tintColor"1 1 1 1"Tint applied to the image entity when inactive (tint transition mode)
pressed-sprite-assetString-Sprite <pc-asset> id shown when pressed (sprite transition mode)
pressed-sprite-frameNumber"0"Frame of the pressed sprite
pressed-tintColor"1 1 1 1"Tint applied to the image entity when pressed (tint transition mode)
transition-modeEnum"tint"How the button reacts to hover/press: "tint" | "sprite"

Example​

A clickable button with tint transitions — hover and press it, then try the hover-tint/pressed-tint colors or a longer fade-duration. The script below wires up the click event using the pattern described next:

Live Example
<pc-app>
    <pc-asset src="https://developer.playcanvas.com/assets/fonts/arial.json" type="font" id="arial"></pc-asset>
    <pc-scene>
        <pc-entity name="camera">
            <pc-camera clear-color="#1d1f2b"></pc-camera>
        </pc-entity>
        <pc-entity name="ui">
            <pc-screen screen-space="true" scale-mode="blend" reference-resolution="640 320"></pc-screen>
            <pc-entity name="button">
                <!-- The image element provides the button's visuals and receives input -->
                <pc-element type="image" anchor="0.5 0.5 0.5 0.5" pivot="0.5 0.5"
                            width="220" height="56" color="#ff8a3c" use-input></pc-element>
                <pc-button transition-mode="tint" hover-tint="0.85 0.85 0.85 1"
                           pressed-tint="0.6 0.6 0.6 1" fade-duration="100"></pc-button>
                <pc-entity name="label">
                    <pc-element type="text" anchor="0.5 0.5 0.5 0.5" pivot="0.5 0.5"
                                font-asset="arial" font-size="24" color="#1d1f2b" text="Click me"></pc-element>
                </pc-entity>
            </pc-entity>
        </pc-entity>
    </pc-scene>
</pc-app>
<script type="module">
    import { whenReady } from '@playcanvas/web-components';

    const button = await whenReady('pc-button');
    const label = document.querySelector('pc-entity[name="label"] > pc-element');
    let clicks = 0;
    button.component.on('click', () => {
        label.setAttribute('text', `Clicked ${++clicks} time${clicks === 1 ? '' : 's'}`);
    });
</script>

You can respond to clicks by listening for the click event on the underlying button component. Wait for the element to finish initializing with whenReady (see Programmatic Access) rather than querying it synchronously:

import { whenReady } from '@playcanvas/web-components';

const button = await whenReady('pc-entity[name="button"] > pc-button');
button.component.on('click', () => {
    console.log('Button clicked!');
});

JavaScript Interface​

You can programmatically create and manipulate <pc-button> elements using the ButtonComponentElement API.