Joystick

<quiet-joystick>

stable

since 1.0

A directional joystick that can be controlled via touch or mouse.

Joysticks are ideal for directional input in games, simulations, and creative tools. They support touch and mouse interactions and feature customizable options for precise control.

<quiet-joystick label="Basic joystick control"></quiet-joystick>

The joystick is designed to be used by touch and mouse users. It does not respond to key presses, as keyboard controls vary depending on each application’s needs. For optimal accessibility, you should consider adding keyboard alternatives on certain devices to ensure your application works well for all users.

Examples Jump to heading

Responding to movement Jump to heading

The joystick emits quiet-joystick-start, quiet-joystick-stop, and quiet-joystick-move events that contain a detail object with the following properties:

angle: degrees (0-359) from the top, increasing clockwise
distance: The normalized distance from the center (0-1)
x: the normalized horizontal position (-1 to 1)
y: the normalized vertical position (-1 to 1)

The move event fires continuously while dragging, while start and stop events fire at the beginning and end of the interaction.

                  Angle: 0°

                  Distance: 0

                  X: 0

                  Y: 0

<div id="joystick__events">
  <quiet-joystick label="Joystick with event feedback"></quiet-joystick>

  <div class="feedback">
    Angle: <span class="angle">0</span>°<br>
    Distance: <span class="distance">0</span><br>
    X: <span class="x">0</span><br>
    Y: <span class="y">0</span>
  </div>
</div>

<script>
  const container = document.getElementById('joystick__events');
  const joystick = container.querySelector('quiet-joystick');
  const angleEl = container.querySelector('.angle');
  const distanceEl = container.querySelector('.distance');
  const xEl = container.querySelector('.x');
  const yEl = container.querySelector('.y');

  function updateValues(detail) {
    angleEl.textContent = Math.round(detail.angle);
    distanceEl.textContent = detail.distance.toFixed(2);
    xEl.textContent = detail.x.toFixed(2);
    yEl.textContent = detail.y.toFixed(2);

  }

  joystick.addEventListener('quiet-joystick-start', event => {
    console.log('start');
    updateValues(event.detail);
  });

  joystick.addEventListener('quiet-joystick-move', event => {
    updateValues(event.detail);
  });

  joystick.addEventListener('quiet-joystick-stop', () => {
    console.log('stop');
    updateValues(event.detail);
  });
</script>

<style>
  #joystick__events {
    quiet-joystick {
      margin-block-end: 1.5rem;
    }
  }
</style>

Adding an icon Jump to heading

Use the thumb slot to add an icon to the joystick's thumb.

<quiet-joystick label="Joystick control with icon">
  <quiet-icon slot="thumb" name="arrows-move"></quiet-icon>
</quiet-joystick>

Showing only on touch devices Jump to heading

If desired, you can use the pointer: coarse media query to hide the joystick on devices that don't support touch.

/* Hide the joystick on non-touch devices */
@media not (pointer: coarse) {
  quiet-joystick {
    display: none;
  }
}

Dead zone Jump to heading

The dead-zone attribute sets a normalized distance (0-1) from the center where joystick movement isn't registered. In this example, the joystick has a 30% dead zone, meaning the thumb must move at least 30% of the way from the center to the edge before events will fire with non-zero values. This can help prevent unintended micro-movements.

                  Angle: 0°

                  Distance: 0

                  X: 0

                  Y: 0

<div id="joystick__dead-zone">
  <quiet-joystick 
    dead-zone="0.3" 
    label="Joystick with 30% dead zone"
  ></quiet-joystick>

  <div class="feedback">
    Angle: <span class="angle">0</span>°<br>
    Distance: <span class="distance">0</span><br>
    X: <span class="x">0</span><br>
    Y: <span class="y">0</span>
  </div>
</div>

<script>
  const container = document.getElementById('joystick__dead-zone');
  const joystick = container.querySelector('quiet-joystick');
  const angleEl = container.querySelector('.angle');
  const distanceEl = container.querySelector('.distance');
  const xEl = container.querySelector('.x');
  const yEl = container.querySelector('.y');

  function updateValues(detail) {
    angleEl.textContent = Math.round(detail.angle);
    distanceEl.textContent = detail.distance.toFixed(2);
    xEl.textContent = detail.x.toFixed(2);
    yEl.textContent = detail.y.toFixed(2);
  }

  joystick.addEventListener('quiet-joystick-move', event => {
    updateValues(event.detail);
  });

  joystick.addEventListener('quiet-joystick-start', event => {
    updateValues(event.detail);
  });

  joystick.addEventListener('quiet-joystick-stop', event => {
    updateValues(event.detail);
  });
</script>

<style>
  #joystick__dead-zone {
    quiet-joystick {
      margin-block-end: 1.5rem;
    }
  }
</style>

Sticky mode Jump to heading

Set the mode attribute to sticky to make the joystick retain its last position after the user releases it, rather than snapping back to the center. This can be useful for scenarios where you want the joystick to hold a value, such as setting a persistent direction or throttle.

Reset

<div id="joystick__sticky">
  <quiet-joystick mode="sticky" label="Sticky joystick control"></quiet-joystick><br>
  <quiet-button>Reset</quiet-button>
</div>

<script>
  const container = document.getElementById('joystick__sticky');
  const joystick = container.querySelector('quiet-joystick');
  const button = container.querySelector('quiet-button');

  button.addEventListener('click', () => {
    joystick.reset();
  });
</script>

Disabling Jump to heading

Set the disabled attribute to prevent the joystick from responding to touch or mouse input. This can be useful when you want to temporarily disable interaction, such as during a loading state or when the joystick's functionality is not applicable.

<quiet-joystick disabled label="Disabled joystick control"></quiet-joystick>

Styling joysticks Jump to heading

You can customize the joystick's appearance using CSS custom properties and parts. Use the --distance readonly custom property to style the joystick based on the distance the thumb has been pulled from the center (0-1). For best results, the joystick's height should always match its width.

<quiet-joystick id="joystick__styling" label="Styled joystick control"></quiet-joystick>

<style>
  #joystick__styling {
    --size: 10rem;
    --thumb-size: 3rem;

    /* Stay forestgreen until 75%, then transition to firebrick from 75% to 100% */
    background-color: color-mix(in oklab, forestgreen, firebrick calc(clamp(0, (var(--distance) - 0.75) / 0.25, 1) * 100%));

    &::part(thumb) {
      background-color: white;
    }
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-joystick> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet-browser@1.0.0/dist/components/joystick/joystick.js';

To manually import <quiet-joystick> from npm, use the following code.

import '@quietui/quiet/dist/components/joystick/joystick.js';

Slots Jump to heading

Joystick supports the following slots. Learn more about using slots

Name	Description
`thumb`	An optional icon to display inside the thumb.

Properties Jump to heading

Joystick has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`label`	An accessible label for the joystick. This won't be shown, but it will be read to assistive devices so you should always include one.	`string`	`''`
`disabled`	Indicates whether the joystick is disabled. When `true`, the joystick does not respond to mouse or touch input.	`boolean`	`false`
`mode`	The operational mode of the joystick. 'normal' snaps back to center on release, 'sticky' retains its last position.	`'normal' 'sticky'`	`'normal'`
`deadZone` `dead-zone`	The normalized distance (0-1) from the center below which no movement is registered.	`number`

Methods Jump to heading

Joystick supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`reset()`	Programmatically resets the joystick's position. Useful for resetting it in sticky mode, e.g. when a game restarts.

Events Jump to heading

Joystick dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-joystick-before-start`	Emitted before interaction begins. Calling `event.preventDefault()` will cancel activation.
`quiet-joystick-start`	Emitted when movement begins.
`quiet-joystick-move`	Emitted continuously during movement. Consider debouncing for performance-sensitive applications.
`quiet-joystick-before-stop`	Emitted before interaction ends. Calling `event.preventDefault()` will cancel deactivation.
`quiet-joystick-stop`	Emitted when movement ends.

CSS custom properties Jump to heading

Joystick supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties

Name	Description	Default
`--size`	The overall width and height of the joystick.	`7rem`
`--thumb-size`	The width and height of the movable thumb.	`2.5rem`
`--distance`	A readonly custom property that represents the normalized distance (0-1) of the thumb from the center, updated dynamically during movement. You can use this to change the joystick's appearance as the user moves the thumb.	`0`

CSS parts Jump to heading

Joystick exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`thumb`	The movable thumb within the joystick.	`::part(thumb)`

Custom States Jump to heading

Joystick has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`disabled`	Applied when the joystick is disabled.	`:state(disabled)`
`dragging`	Applied when the joystick is being dragged.	`:state(dragging)`

Joystick

Examples Jump to heading #

Responding to movement Jump to heading #

Adding an icon Jump to heading #

Showing only on touch devices Jump to heading #

Dead zone Jump to heading #

Sticky mode Jump to heading #

Disabling Jump to heading #

Styling joysticks Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS custom properties Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #