vue-dat-gui

A Vue3 port of the popular dat.GUI library.

This is a lightweight graphical user interface to change variables in Javascript (or Typescript). Useful for all your demos or experimental codes.

DEMO ✨

Check out the demo page.

Used by:

• cyrilf/microbios: Cellular automata simulation / Github
• ...
• Feel free to submit a PR to add your website.

INSTALL 💻

Option 1 - Install from NPM

npm install --save @cyrilf/vue-dat-gui

Then the usage is:

import { createApp } from "vue";
import VueDatGui from "@cyrilf/vue-dat-gui";
import "@cyrilf/vue-dat-gui/dist/style.css";

/* your code */
// ...

const app = createApp(App);
app.use(VueDatGui);

app.mount("#app");

Option 2 - Instal via CDN file

In your head tag, include the following code:

<link
  rel="stylesheet"
  href="https://unpkg.com/@cyrilf/vue-dat-gui@latest/dist/style.css"
/>
<script type="module" lang="ts">
  import {
    createApp,
    computed,
    ref,
  } from "https://unpkg.com/vue@3/dist/vue.esm-browser.js";
  import VueDatGui from "https://unpkg.com/@cyrilf/vue-dat-gui@latest/dist/vue-dat-gui.js";

  createApp({
    /*your code*/
  })
    .use(VueDatGui)
    .mount("#app");
</script>

VERSIONS #️⃣

Vue3

The main branch contains code for Vue3. It's refering to the tags v1.x.

Vue2

The deprecated branch vue2 is for Vue2 support. It's refering to the tags v0.x. You can find the README with all the required information for this version.

USAGE 🖱️

You can always refer to the public/index.html file for the most up-to-date example of how to use it. (keep in mind that this is a demo version using the CDN version of Vue and vue-dat-gui, so it's a bit different than the usage in your app).

The demo page is also available.

In your view:

<div class="app">
  <DatGui
    closeText="Close controls"
    openText="Open controls"
    closePosition="bottom"
  >
    <DatColor v-model="background" label="Background" />
    <DatNumber v-model="titleFontSize" label="Title font-size" />
    <DatString v-model="title" label="Title" />
    <DatButton @click="triggerAlert" label="Trigger alert" />
    <DatFolder label="Picture">
      <DatSelect v-model="pictureUrl" :items="pictures" label="Picture" />
      <DatBoolean v-model="showPicture" label="Show Picture" />
      <DatFolder label="Box shadow">
        <DatBoolean
          v-model="boxShadow.disabled"
          :label="boxShadow.disabled ? 'Enable options' : 'Disable options' "/>
        <DatNumber
          v-model="boxShadow.offsetX"
          :min="-100"
          :max="100"
          :step="1"
          label="Offset X"
          :disabled="boxShadow.disabled"
        />
        <DatNumber
          v-model="boxShadow.offsetY"
          :min="-100"
          :max="100"
          :step="1"
          label="Offset Y"
          :disabled="boxShadow.disabled"
        />
        <DatNumber
          v-model="boxShadow.blurRadius"
          :min="0"
          :max="100"
          :step="1"
          label="Blur radius"
          :disabled="boxShadow.disabled"
        />
        <DatNumber v-model="boxShadow.spreadRadius" label="Spread radius" :disabled="boxShadow.disabled" />
        <DatColor v-model="boxShadow.color" label="Color" :disabled="boxShadow.disabled" />
      </DatFolder>
    </DatFolder>
  </DatGui>
</div>

In your javascript:

// <script setup lang="ts">
import { computed, ref } from "vue";

const pictures = [
  {
    name: "forest",
    value:
      "https://images.unsplash.com/photo-1516214104703-d870798883c5?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=750&q=80",
  },
  {
    name: "mountain",
    value:
      "https://images.unsplash.com/photo-1526080676457-4544bf0ebba9?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=750&q=80",
  },
  {
    name: "beach",
    value:
      "https://images.unsplash.com/photo-1520942702018-0862200e6873?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=750&q=80",
  },
];

const background = ref("#cdeecc");
const titleColor = ref("#077d43");
const titleFontSize = ref(75);
const title = ref("vue-dat-gui");
const showPicture = ref(true);
const boxShadow = ref({
  disabled: false,
  offsetX: 27,
  offsetY: 27,
  blurRadius: 75,
  spreadRadius: 2,
  color: "rgba(3, 23, 6, 1)",
});

const pictureStyle = computed(() => {
  const { offsetX, offsetY, blurRadius, spreadRadius, color } = boxShadow.value;
  return {
    "box-shadow": `${offsetX}px ${offsetY}px ${blurRadius}px ${spreadRadius}px ${color}`,
  };
});

const triggerAlert = () => alert("Yeah, you pressed it!");

let pictureUrl = ref(pictures[0].value);
const nextPicture = () => {
  const currentIndex = pictures.findIndex(
    (picture) => picture.value === pictureUrl.value
  );
  const nextIndex = (currentIndex + 1) % pictures.length;
  pictureUrl.value = pictures[nextIndex].value;
};
// </script>

Components

DatGui

The main menu that wraps all components. (required)

<DatGui
  v-model:open="isOpen"
  open-text="Open Controls"
  close-text="Close Controls"
  close-position="bottom"
>
  <!-- other components -->
</DatGui>

DatBoolean

A checkbox element

<DatBoolean v-model="isActive" label="Is active?" />

DatButton

A button element

<DatButton @click="onSurpriseClick" label="Surprise me!" />

DatColor

A color-picker element

<DatColor v-model="mainColor" label="Main color" />

DatFolder

A folder element

<DatFolder v-model:open="isOpen" label="Optional settings">
  <!-- other components -->
</DatFolder>

DatNumber

A number input element. If min and max are specified, then a slider is added.

<DatNumber
  v-model="areaWidth"
  :min="0"
  :max="1000"
  :step="5"
  :showSlider="false"
  label="Area width"
/>

*`Note`**: it's the "order of magnitude of the absolute difference between max and min and returns a power of 10 corresponding to that order of magnitude".

DatSelect

A select element

<DatSelect v-model="mainPicture" :items="pictures" label="Main picture" />

Type Item = { name: string; value: string; } | string | number

DatString

A text input element

<DatString v-model="username" label="Username" />

Deploy

./deploy

Feel free to open any Pull Request/Issues.

THANKS 👌

• dat.GUI for the initial project