XYSlider

The XYSlider component allows users to select a value in a two-dimensional space, providing a more intuitive way to select values that require both horizontal and vertical input.

The slider automatically handles the selection of a value between a minimum and maximum range on the horizontal and vertical axes. The slider itself provides slots to customize its appearance and behavior. For example you can customize its background or the handle to make it more visually appealing or to fit the design of your UI.

Usage

Using the XYSlider component is straightforward. You can import it and use it in your application as follows:

import XYSlider from '@components/Basic/XYSlider/XYSlider';

const App = () => {
    return (
        <XYSlider maxX={150} maxY={150} value={{x: 50, y: 50}} />
    );
};

export default App;

API

Props

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the component’s root element.
class	string	""	Additional CSS classes to apply to the component.
ref	XYSliderRef | undefined	undefined	A reference to the component that gives you access to its methods and the underlying HTML element. Useful if you need to set the value of the slider programmatically.
value	{x:number, y: number}	{ x: 50, y: 50 }	The current value of the slider. Use this to control or set the slider’s position.
minX	number	0	The minimum value that the slider can select on the X-axis.
minY	number	0	The minimum value that the slider can select on the Y-axis.
maxX	number	100	The maximum value that the slider can select on the X-axis.
maxY	number	100	The maximum value that the slider can select on the Y-axis.
step	number	1	The base unit for value changes. Used primarily for gamepad inputs to calculate movement speed and precision.
onChange	(value: {x:number, y: number}) => void	undefined	A function that is called every time the slider’s value has changed. It can be used to retrieve the up to date value of the slider.
onAction	Record<string, (scope?: string, ...args: any[]) => void>	undefined	Extends or overrides the component’s default navigation action handlers. See Implemented Navigation Actions for details.
anchor	string | HTMLElement	undefined	Links navigation to another element. When the anchor element is focused, the stepper’s actions will execute. Can be a CSS selector or HTMLElement.

Ref API

To interact with the XYSlider programmatically, you can use the XYSliderRef interface. This interface provides properties and methods to access and manipulate the component’s state.

Properties

Property	Type	Description
element	HTMLDivElement	A reference to the XYSlider’s root HTML element, useful for DOM access or styling.
value	Accessor<{x: number, y: number}>	The current value of the slider. Use value() to get the latest value.

Methods

Method	Parameters	Return Value	Description
changeValue	newValue: {x: number, y: number}	void	Programmatically sets a new value for the XYSlider.

Slots

XYSlider.Background

Customizes the slider’s background. Use this slot to apply add a custom background to the slider, such as a gradient or an image.

Properties

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the slider’s background.
class	string	""	Additional CSS classes to style the slider’s background.
children	JSX.Element	""	Content to be rendered inside the background slot. This can be used to add custom elements or styles.

Usage

import XYSlider from '@components/Basic/XYSlider/XYSlider';
import Absolute from '@components/Layout/Absolute/Absolute';

const App = () => {
    return (
        <XYSlider>
            <XYSlider.Background style={{ background: 'linear-gradient(to right, #ff7e5f, #feb47b)' }}>
                <Absolute style={{ width: '100%', height: '100%', background: 'rgba(0, 0, 0, 0.2)' }}>
                    Custom Background
                </Absolute>
            </XYSlider.Background>
        </XYSlider>
    );
};

export default App;

XYSlider.Handle

Customizes the draggable handle of the slider. Use this slot to apply custom styles or classes to the slider’s handle.

Properties

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the slider’s handle.
class	string	""	Additional CSS classes to style the slider’s handle.

Usage

import XYSlider from '@components/Basic/XYSlider/XYSlider';

const App = () => {
    return (
        <XYSlider>
            <XYSlider.Handle style={{ width: '2vmax', height: '2vmax', background: 'black' }} />
        </XYSlider>
    );
};

export default App;

Implemented Navigation Actions

The XYSlider component implements the following navigation actions by default:

Action Name	Behavior
pan	Moves the slider handle based on 2D axis input. Includes acceleration and smoothing logic.

Note

The XYSlider uses the step prop to determine base movement speed. It employs a dynamic acceleration system where pushing the stick further increases the speed multiplier, allowing for both precise adjustments (slight tilt) and rapid movement (full tilt). Read more here

You can extend the XYSlider with additional navigation actions or override the default behavior using the onAction prop:

import XYSlider from '@components/Basic/XYSlider/XYSlider';

<XYSlider
    onAction={{
        'select': () => console.log('Selecting XYSlider'),
        'pan': (_, axis: [number, number]) => console.log(`x: ${axis[0]}, y: ${axis[1]}`),
    }} />

For more information about navigation actions, see the Navigation component documentation.

Guide

Retrieve and use the slider value

• To get the current value of the XYSlider component, use the onChange prop.
• When you save the value in a state variable, you can use it in your UI to display or process the slider’s value.

Steps

1. Define a state variable (e.g., using createSignal) to store the slider value.
2. Pass a callback to the onChange prop that updates this state variable.
3. Use the state variable wherever you need the slider’s value.

import XYSlider from '@components/Basic/XYSlider/XYSlider';
import { createSignal } from 'solid-js';

const App = () => {
    const [sliderValue, setSliderValue] = createSignal({x: 50, y: 50});

    return (
        <>
            <XYSlider onChange={(value) => setSliderValue(value)} />
            <div>X: {sliderValue().x} | Y: {sliderValue().y}</div>
        </>
    );
};

export default App;

Set the value of the slider programmatically

The Slider component lets you set the value through code.

Steps

1. Declare a ref variable with type XYSliderRef and pass it to the XYSlider component.
2. Call ref.changeValue() from anywhere (e.g., a keyboard event or external button) to set the value programmatically.

import XYSlider { XYSliderRef } from '@components/Basic/XYSlider/XYSlider';

const App = () => {
    let sliderRef!: XYSliderRef;

    const handleKeyPress = (e: KeyboardEvent) => {
        if (e.keyCode !== 13) return

        sliderRef.changeValue({x: 150, y: 50});
    }

    return (
        <XYSlider ref={sliderRef} maxX={200} />
    );
};

export default App;

Adjusting gamepad movement speed and precision

The XYSlider is designed to work out-of-the-box with the pan action of the Navigation component which uses the right analogue stick of the gamepad.

To tune the feel of the gamepad control, adjust the step prop.

• A smaller step (e.g., 1) allows for pixel-perfect precision but might be slow on large ranges.
• A larger step (e.g., 10) makes the slider faster but less precise.

<XYSlider maxX={1000} step={5} /> // Increases base speed for large range

Note

If you are working with very small values (e.g., 0.0 to 1.0), consider using a smaller step (e.g., 0.1) to maintain precision.