{"id":19218211,"url":"https://github.com/greggman/muigui","last_synced_at":"2025-05-13T00:14:17.523Z","repository":{"id":42374998,"uuid":"509691955","full_name":"greggman/muigui","owner":"greggman","description":"a simple ui library","archived":false,"fork":false,"pushed_at":"2025-04-10T20:56:41.000Z","size":2315,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-13T00:14:08.865Z","etag":null,"topics":["gui","muigui","ui"],"latest_commit_sha":null,"homepage":"http://muigui.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/greggman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-02T07:43:16.000Z","updated_at":"2025-04-26T07:03:04.000Z","dependencies_parsed_at":"2023-12-04T05:35:59.541Z","dependency_job_id":"77339ebf-3050-4006-9824-d0a961f15a7f","html_url":"https://github.com/greggman/muigui","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/greggman%2Fmuigui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/greggman%2Fmuigui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/greggman%2Fmuigui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/greggman%2Fmuigui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/greggman","download_url":"https://codeload.github.com/greggman/muigui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253843225,"owners_count":21972874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gui","muigui","ui"],"created_at":"2024-11-09T14:25:43.820Z","updated_at":"2025-05-13T00:14:17.502Z","avatar_url":"https://github.com/greggman.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# muigui (⍺)\n\nA simple Web UI library.\n\n[See docs here](https://muigui.org)\n\nmuigui is a simple UI library in the spirit of\n[dat.gui](https://github.com/dataarts/dat.gui) and/or [lil-gui](https://github.com/georgealways/) and [tweakpane](https://cocopon.github.io/tweakpane/)\n\n## Usage\n\n```js\nimport GUI from 'https://muigui.org/dist/0.x/muigui.module.js';\n```\n\nor\n\n```html\n\u003cscript src=\"https://muigui.org/dist/0.x/muigui.min.js\"\u003e\u003c/script\u003e\n```\n\nThen\n\n```js\nconst s = {\n  someNumber: 123,\n  someString: 'hello',\n  someOption: 'dog',\n  someColor: '#ED3281',\n  someFunction: () =\u003e console.log('called')\n};\n\nconst gui = new GUI();\ngui.add(s, 'someNumber', 0, 200);  // range 0 to 200\ngui.add(s, 'someString');\ngui.add(s, 'someOption', ['cat', 'bird', 'dog']);\ngui.addColor(s, 'someColor');\ngui.add(s, 'someFunction');\n```\n\nproduces\n\n\u003cimg src=\"./images/muigui-screenshot.png\" width=\"250\"\u003e\n\n## Why\n\nSo, to be honest, I like [tweakpane](https://cocopon.github.io/tweakpane/) and\nI didn't know about it when I started this library. That said, I've looked\ninto using tweakpane and it doesn't meet my needs as of v4.0.0. Examples below\n\n* ## Simpler\n  \n  I wanted certain things to be simpler. For example, in dat.gui/lil.gui/tweakpane, if I wanted\n  to store radians in code but show degrees in the UI I had to jump through\n  hoops. I could either, store degrees and convert 😢\n\n  ```js\n  const settings = {\n    angle: 45,\n  };\n  gui.add(settings, 'angle', -360, 360);\n\n  ...\n     const rotation = settings.angle * Math.PI / 180\n  ```\n\n  That's bad IMO. I shouldn't have to refactor my code to fit the GUI.\n\n  I can make some proxy class that presents degrees to the GUI\n  and stores them in radians like this\n\n  ```js\n  class DegRadHelper {\n    constructor( obj, prop ) {\n      this.obj = obj;\n      this.prop = prop;\n    }\n    get value() {\n      return this.obj[this.prop] * 180 / Math.PI;\n    }\n    set value(v) {\n      this.obj[this.prop] = v * Math.PI / 180;\n    }\n  }\n  const settings = {\n    angle: Math.PI * 0.5,\n  };\n  gui.add(new DegRadHelper(settings, 'angle'), 'value', -360, 360);\n  ```\n\n  But that looks poor to use. What is `'value'`?? 😭\n\n  So, muigui handles that slightly nicer in the form of converters.\n\n  ```js\n  const settings = {\n    angle: Math.PI * 0.5,\n  };\n  const degToRad = d =\u003e d * Math.PI / 180;\n  const radToDeg = r =\u003e r * 180 / Math.PI;\n  gui.add(s, 'angleRad', {\n    min: -360, max: 360,\n    converters: {\n      to: radToDeg,\n      from: v =\u003e [true, degToRad(v)],\n    }});\n  ```\n\n  Typically I'll pull out the settings like this\n\n  ```js\n  const degToRad = d =\u003e d * Math.PI / 180;\n  const radToDeg = r =\u003e r * 180 / Math.PI;\n  const radToDegSettings {\n    min: -360, max: 360,\n    converters: {\n      to: radToDeg,\n      from: v =\u003e [true, degToRad(v)],\n    }});\n  ```\n\n  And then I can use it like this\n\n  ```js\n  const settings = {\n    angle: Math.PI * 0.5,\n    rotation: Math.PI * 0.25,\n  };\n  gui.add(s, 'angleRad', radToDegSettings);\n  gui.add(s, 'rotation', radToDegSettings);\n  ```\n\n  You provide converters where `to` converts to the form the UI wants\n  and `from` converts back. The reason `from` returns a tuple is that\n  it's used to convert the text and gives you a chance to say the text\n  does not match the required format in which case you return `[false]`\n\n  Other examples of simpler: Want a drop-down for numbers?\n\n  ```js\n  const settings = { speed: 1 }\n\n  // tweakpane\n  pane.addBinding(settings, speed, {\n    options: {\n      slow: 0,\n      medium: 1,\n      fast: 2,\n    }\n  })\n\n  // muigui\n  gui.add(settings, 'speed', ['slow', 'medium', 'fast']);\n  ```\n\n  Want a drop-down for strings\n\n  ```js\n  const settings = { alphaMode: 'opaque' }\n\n  // tweakpane\n  pane.addBindng(settings, 'alphaMode', {\n    options: {\n      'opaque': 'opaque',\n      'premultiplied': 'premultiplied',\n    }\n  });\n\n  // muigui\n  gui.add(settings, 'alphaMode', ['opaque', 'premultiplied']);\n  ```\n\n  Of course you can also pass in key/value settings like tweakpane.\n\n* ## Color formats and storage\n\n  I often work with WebGL and WebGPU. The most common colors are in an array or a typedArray\n  \n  ```js\n  const uniforms = {\n    color1: [1, 0.5, 0.25],                   // orange\n    color2: new Float32Array([0, 1, 1]),      // cyan\n    color3: new Uint8Array([0, 128, 0, 128]), // transparent green\n  };\n  ```\n\n  Neither dat.gui, lil.gui, nor tweakpane can edit these AFAICT. (2023)\n  You'd have to jump\n  through the hoops like the `DegRadHelper` example above but it's not\n  that easy because, if you're showing the value textually\n  then you want that value to be the one you want to show the user,\n  not the value the editor wants.\n\n  This is still an issue in muigui where it uses the browser's built\n  in color editor in parts. That editor might show 0-255 values but if it's\n  editing 0 to 1 values it'd be nice if the editor showed 0 to 1 values.\n\n  muigui does handle this in the text part of it's color display. If you\n  ask it to edit 0 to 1 values it shows 0 to 1 values in the text part.\n  The reason you need the text part is so you can copy and paste colors\n\n  muigui also edits hsl colors. By that I don't mean the editor can\n  switch to an HSL editor, I mean the actual value that comes out\n  is `hsl(hue, sat, luminance)` and not some RGB value. Like the number\n  conversions, it would be easy to add `hsv`, `hsb`, maybe `labch` etc...\n\n* ## More Use Cases\n\n  In some projects, I'd end up writing a small\n  app with an HTML form and then have to write all the code to parse\n  the form and I'd be thinking \"It would be so nice if I could use\n  the same API as dat.gui 🙁\n\n  So, I thought I'd try to write a library that handled that case.\n\n## Exploration\n\nI also wanted to explore various things though many of them\nhave not made it into muigui yet.\n\n* ## PropertyGrid\n\n  I'm sure the first app to do this was something from the 60s or 70s\n  in Smalltalk or something but my first experience was C#. In C#\n  the UI library had a `PropertyGrid` which you could pass any class\n  and with would auto-magically make UI to edit the public fields\n  of that class. If you've ever used Unity, it's the same. You declare\n  a class and it immediately shows a UI for all of its public properties.\n\n  That's easier in a typed language than a more loose language like\n  JavaScript.\n\n  I'm still experimenting with ideas but it sure would be nice to\n  get that for JS. Just give it an object and get a UI. You can\n  then customize later.\n\n  To be more concrete. Here's some code to setup a GUI\n  \n  ```js\n  const s = {\n    someNumber: 123,\n    someString: 'hello',\n    someOption: 'dog',\n    someColor: '#ED3281',\n    someFunction: () =\u003e console.log('called')\n  };\n\n  const gui = new GUI();\n  gui.add(s, 'someNumber', 0, 200);  // range 0 to 200\n  gui.add(s, 'someString');\n  gui.add(s, 'someOption', ['cat', 'bird', 'dog']);\n  gui.addColor(s, 'someColor');\n  gui.add(s, 'someFunction');\n  ```\n\n  I'd really like it to be this\n\n  ```js\n  const s = {\n    someNumber: 123,\n    someString: 'hello',\n    someOption: 'dog',\n    someColor: '#ED3281',\n    someFunction: () =\u003e console.log('called')\n  };\n\n  const gui = new GUI();\n  gui.add(s);\n  ```\n\n  You could implement that like this\n\n  ```js\n  for (const key of Object.keys(s)) {\n     gui.add(s, key);\n  }\n  ```\n\n  But that won't work. `someNumber` could only become\n  a `TextNumber` because there's no range. `someOption` would\n  only become a `Text` because there's no info that it's an enum.\n  `someColor` would become a `Text` because there's no info that\n  it's a color. So in the end only 2 of the 5 would work without\n  having to provide more info.\n\n  It's not clear in JS that adding that info would be a win\n  for keeping it simple but it sure would be nice. I've thought\n  about passing a second object with options. The simplest version\n  would be something like this\n\n  ```js\n  const s = {\n    someNumber: 123,\n    someString: 'hello',\n    someOption: 'dog',\n    someColor: '#ED3281',\n    someFunction: () =\u003e console.log('called')\n  };\n  const argsByName: {\n    someNumber: [{ min: 1, max: 200 }],\n    someOption: [['cat', 'bird', 'dog']],\n    someColor: [{type: 'color'}],\n  };\n  addObject(s, argsByName) {\n    for (const key of Object.keys(s)) {\n       gui.add(s, key, ...(argsByName[key] || []);\n    }\n  }\n  ```\n\n  But that's not really what you get from a typed system.\n  In a typed system, the fact that `someOption` is an enum\n  is known from its type. Similar that `someColor` is a\n  a color is known from its type. `someNumber` is still\n  problematic because it needs a range which is probably\n  not part of its type.\n\n  In any case, It'd be nice to find a way to get an\n  instant UI like C#/Unity does.  \n\n* ## Modularity\n\n  Ideally I'd like it to be easy to make UIs based on collections\n  of parts. A simple example might be a 3 component vector\n  editor that is the combination of 3 number editors.\n\n  I'm still experimenting. While muigui has components that\n  do this I'm not happy with the API ergonomics yet and is\n  why I haven't documented them. In fact I'd pretty much like\n  to re-write all of the code for like the 4th time 😅 but\n  I hope to keep the normal usage API the same.\n\n  Similarly I'd like to more easily split layout so it's trivial\n  to layout sub components. Again, still experimenting.\n\n* ## Don't over specialize\n\n  This might be ranty, but I find libraries that try to do too much,\n  frustrating. In this case, it would\n  be a library that graphs data for you. The problem\n  with this functionality is that there is no end to\n  the number of features that will be requested.\n\n  You start with \"graph an array of numbers\".\n  Then you'll be asked to be able to supply a range.\n  Then you'll be asked to allow more than one array\n  for the graph.\n  You'll next be asked to let you specify a different\n  color for each array. Next you'll be asked to draw\n  axes, in different colors, with different units,\n  and labels. Then you'll be asked to have an option\n  to fill under the graph. Etc, etc, etc... forever.\n\n  In this case, It's arguably better to provide\n  a canvas and let the developer write their\n  own graphing code. Maybe provide an example or\n  a simple helper for the simplest case.\n\n  They can even choose when to update vs having to\n  choose an interval.\n\n  Let's compare\n\n  ```js\n  // tweakpane\n  const pane = new Pane();\n  pane.addBinding(PARAMS, 'wave', {\n    readonly: true,\n    view: 'graph',\n    min: -1,\n    max: +1,\n  });\n\n  // muigui\n  const gui = new GUI();\n  helpers.graph(gui.addCanvas('wave'), waveData, {\n    min: -1,\n    max: +1,\n  });\n  ```\n\n  It wasn't any harder to use, but the fact that we\n  just returned a canvas and left the rest outside\n  the library made it way more flexible.\n\n  Another example might be monitoring. Some libraries\n  provide a way to make a GUI part poll its value for\n  the purpose of displaying values but does that really\n  need to be part of the library?\n\n  Compare\n\n  ```js\n  pane.addBinding(PARAMS, 'data', {\n    readonly: true,\n    interval: 200,\n  });\n  ```\n\n  vs\n\n  ```js\n  const label = gui.addLabel();\n  setInterval(() =\u003e {\n    label.text(JSON.stringify(PARAMS.data, null, 2));\n  }, 200);\n  ```\n\n  They're about the same amount of code but in the first version\n  you can only make that area show the data at `PARAMS.data` where\n  as in the 2nd version you can show whatever you want. Data\n  for the currently select item, player stats, a text based graph.\n  You're not limited to only properties of `PARAMS` nor are you\n  limited to how it chooses to format those.\n\n  This problem of providing too specialized a solution\n  is endemic throughout the library ecosystem of pretty much\n  every language.\n\n  There's a balance, but in general, if you need\n  to add more and more options then it was probably the\n  wrong solution. It's better to provide the\n  building blocks.\n\n  `\u003c/rant\u003e` 😅\n\n## No Save/Restore\n\nThe problem with save/restore in lil.gui etc is it assumes the data\nI want to edit can be serialized to JSON\n\nJust as the simplest example I can think of\n\n```js\nconst material = new THREE.MeshBasicMaterial();\n\nconst gui = new GUI();\ngui.addColor(material, 'color');\n```\n\nIt makes no sense to save/restore here. I'm editing a three.js material.\nIf I wanted to serialize anything I'd serialize the material.\n\nOtherwise I can just save the stuff I passed to the GUI.\n\n```js\n  const s = {\n    someNumber: 123,\n    someString: 'hello',\n    someOption: 'dog',\n    someColor: '#ED3281',\n  };\n\n  // save\n  const str = JSON.stringify(s);\n\n  // restore\n  Object.assign(s, JSON.parse(str));\n  gui.updateDisplay(); \n```\n\nIn other words, the serialization is too specialized. It's trivial\nto call `JSON.stringify` on data that serializable. No need to put\nserialization in the GUI. Note: I get that you might want to save\nsome hidden gui state like whether or not a folder is expanded.\nYou still run into the issue though that the data being edited\nmight not be easily serializable so you'd have to find another solution.\n\nTo put it another way, it's not the responsibility of a UI library\nto serialize.\n\n## Future\n\nI'm under sure how much time I'll continue to put into this.\nI get the feeling other people are far more motivated to make\nUIs. Maybe if I'm lucky they'll take some inspiration from\nthe thoughts and ideas above and I'll find they've covered it all.\n\n## License\n\n[MIT](https://github.com/greggman/muigui/blob/main/LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreggman%2Fmuigui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgreggman%2Fmuigui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreggman%2Fmuigui/lists"}