Skip to main content

Custom Visual

Replace the default look of a UI Kit 4.0.0 component with a custom visual, such as a RoundedRectangleVisual with your own gradients for each interaction state.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
  • SnapchatNot supported
  • SPECSFully supported
  • Camera Kit WebNot supported
  • Camera Kit MobileNot supported

Platform details

  • Snapchat — Not supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported.

  • Camera Kit Mobile — Not supported.

You can swap out the default visual for a UI Kit component by creating a custom visual. This page shows how to do this in TypeScript for a Button, for developers who need a look that the UI Kit themes don't provide. To change a button between the looks UI Kit already has, set its Theme, Shape, and Style instead (see Button); a custom visual replaces the theme's styling for that component.

A button with a custom gradient visual in its hovered state

How a custom visual replaces a UI Kit component's default visual

A UI Kit visual element draws itself through a Visual (see Architecture). When it initializes, it creates a default Visual from its theme, unless one is already assigned. To use your own, create a Visual and set the element's visual property before you call initialize().

A RoundedRectangleVisual takes a style with one entry per interaction state. Each state is a RoundedRectangleVisualState: the fill (baseType of 'Color', 'Gradient', or 'Texture', with baseColor, baseGradient, or baseTexture) and an optional border (hasBorder, borderSize, borderType, borderColor or borderGradient). The state names come from the StateName enum: default, hovered, triggered, inactive, error, errorHovered, toggledDefault, toggledHovered, and toggledTriggered.

Besides RoundedRectangleVisual, UI Kit 4.0.0 includes BeveledPrismVisual, which the System 3.0 Prism styles use.

Apply a custom visual to a Button

The script below finds the Button on its own scene object, builds a RoundedRectangleVisual with a gradient for the default, hovered, and triggered states, assigns it, and then initializes the button. Put it on the same scene object as the Button.

import { Button } from 'UIKit.lspkg/Scripts/Components/Button/Button';
import {
RoundedRectangleVisual,
RoundedRectangleVisualState,
} from 'UIKit.lspkg/Scripts/Visuals/RoundedRectangle/RoundedRectangleVisual';
import { StateName } from 'UIKit.lspkg/Scripts/Components/Element';

const COLORS = {
// More saturated yellow, black, white with rich tonal variations
lightYellow: new vec4(1.0, 0.99, 0.75, 1), // #FFFC40 - Rich cream yellow
yellow: new vec4(0.95, 0.88, 0.15, 1), // #F2E026 - Vibrant yellow
darkYellow: new vec4(0.8, 0.7, 0.0, 1), // #CCB300 - Deep golden yellow

white: new vec4(0.99, 0.99, 0.99, 1), // #FCFCFC - Bright white
lightGray: new vec4(0.88, 0.88, 0.88, 1), // #E0E0E0 - Light gray
darkGray: new vec4(0.2, 0.2, 0.2, 1), // #333333 - Dark gray
black: new vec4(0.02, 0.02, 0.02, 1), // #050505 - Rich black
};

/**
* ExampleButtonCustomVisual is a script that applies a custom visual to a button.
* It uses the RoundedRectangleVisual class to create a rounded rectangle with a custom visual.
*/

@component
export class ExampleButtonCustomVisual extends BaseScriptComponent {
onAwake() {
const button = this.sceneObject.getComponent(
Button.getTypeName()
) as Button;
const customStyle: Partial<Record<StateName, RoundedRectangleVisualState>> =
{
default: {
baseType: 'Gradient',
hasBorder: true,
borderSize: 0.125,
borderType: 'Color',
borderColor: COLORS.lightGray,
baseGradient: {
enabled: true,
type: 'Rectangle',
stop0: { enabled: true, percent: 0, color: COLORS.white },
stop1: { enabled: true, percent: 0.3, color: COLORS.lightGray },
stop2: { enabled: true, percent: 0.7, color: COLORS.darkGray },
stop3: { enabled: true, percent: 1.0, color: COLORS.black },
},
},
hovered: {
baseGradient: {
enabled: true,
type: 'Rectangle',
stop0: { enabled: true, percent: 0, color: COLORS.lightYellow },
stop1: { enabled: true, percent: 0.2, color: COLORS.yellow },
stop2: { enabled: true, percent: 0.6, color: COLORS.darkYellow },
stop3: { enabled: true, percent: 1.0, color: COLORS.darkGray },
},
},
triggered: {
baseGradient: {
enabled: true,
type: 'Rectangle',
stop0: { enabled: true, percent: 0, color: COLORS.yellow },
stop1: { enabled: true, percent: 0.3, color: COLORS.white },
stop2: { enabled: true, percent: 0.7, color: COLORS.lightGray },
stop3: { enabled: true, percent: 1.0, color: COLORS.black },
},
},
};
const customVisual = new RoundedRectangleVisual({
sceneObject: button.sceneObject,
style: customStyle,
});

button.visual = customVisual;
button.initialize();
}
}
  • Architecture: how Elements, Visuals, and VisualElements fit together.
  • Extend Component: subclass a component and create its visual in code.
  • Button: the theme styles a custom visual replaces.