Gathering detailed insights and metrics for winbox
Gathering detailed insights and metrics for winbox
WinBox is a modern HTML5 window manager for the Web.
Installations
npm install winboxDeveloper Guide
BETA
Typescript
No
Module System
ESM, UMD
Node Version
16.20.0
NPM Version
9.6.6
Releases
28
Languages
2
JavaScript
Less
JavaScript (85.47%)
Less (14.53%)
Developer
nextapps-de
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
Apache-2.0 License
6,320 Stars
158 Commits
207 Forks
69 Watchers
2 Branches
8 Contributors
Updated on Jul 11, 2025
Maintainers
1
Package Meta Information
Latest Version
0.2.82
Package Id
winbox@0.2.82
Unpacked Size
154.09 kB
Size
41.05 kB
File Count
37
NPM Version
9.6.6
Node Version
16.20.0
Published on
Jul 13, 2023
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Modern window manager for the web: lightweight, outstanding performance, no dependencies, fully customizable, open source!
Demo • Getting Started • Options • API • Themes • Customize • Changelog
Live Demo and Code Examples
https://nextapps-de.github.io/winbox/
Support this Project
Hello my name is Thomas, also known as ts-thomas. This is a personal project which I fully made in my free time. It is hosted by the Github account from the company Nextapps where I work to give it more exposure. I have never received any financial support for this project from the company Nextapps as some of you might have guessed, since it is a free and open source project. I'm really happy that WinBox.js is getting so much positive feedback and also feature requests. Please feel free to support me by making a personal donation which helps me a lot to keep this project alive and also to providing all the contribution to keep WinBox.js on a professional top-end level.
Thanks a lot, Thomas (ts-thomas)
Plugins / Add-ons / Extensions
Vue 2 and 3 (a wrapper component that adds the ability to mount Vue components in WinBox.js):
https://github.com/wobsoriano/vue-winbox
A React controlled component for WinBox.js, with full Reactful props and state.:
https://github.com/rickonono3/react-winbox
Getting Started
Get Latest Stable Build (Recommended):
| Bundle: (all assets bundled into one single file: js + css + html + icons) | ||
| winbox.bundle.min.js | Download | https://rawcdn.githack.com/nextapps-de/winbox/0.2.82/dist/winbox.bundle.min.js |
|
Non-Bundled: (js and css are separated, css includes icons as base64) | ||
| winbox.min.js | Download | https://rawcdn.githack.com/nextapps-de/winbox/0.2.82/dist/js/winbox.min.js |
| winbox.min.css | Download | https://rawcdn.githack.com/nextapps-de/winbox/0.2.82/dist/css/winbox.min.css |
|
Sources: (not bundled at all, images as url to original resources) | ||
| ES6 Modules | Download | The /src/js folder of this Github repository |
| LESS Files (source) | Download | The /src/css folder of this Github repository |
| winbox.css (compiled) | Download | https://rawcdn.githack.com/nextapps-de/winbox/0.2.82/src/css/winbox.css |
| src.zip | Download | Download all source files including image original resources. |
Get Latest (NPM):
1npm install winbox
Use Bundled Version (Recommended)
The bundled version includes all assets like js, css, html and icon images as base64.
A best practice is to load the library as async and use some modern preloading mechanism:
1<html> 2<head> 3 <link rel="preload" href="winbox.bundle.min.js" as="script"> 4</head> 5<body> 6 <!-- 7 8 HTML CONTENT 9 10 --> 11 <!-- BOTTOM OF BODY --> 12 <script src="winbox.bundle.min.js" async></script> 13 <!-- YOUR SCRIPT --> 14 <script src="my-script.js" defer></script> 15</body> 16</html>
When you get troubles with unavailable references then remove the async or defer from this example and invest some minutes later to find out how you can properly load js assets asynchronously today.
Use Non-Bundled Version
The non-bundled version needs to load js and css separately (css already includes icons as base64).
1<html> 2<head> 3 <link rel="stylesheet" href="winbox.min.css"> 4 <script src="winbox.min.js"></script> 5</head> 6<body></body> 7</html>
You can also load the non-bundled version in the same way.
ES6 Modules
The ES6 modules are located in src/js/. But you need to load the stylesheet file explicitly since this is just automatically loaded by the bundled version.
1<head> 2 <link rel="stylesheet" href="dist/css/winbox.min.css"> 3</head>
1<script type="module"> 2 import WinBox from "./src/js/winbox.js"; 3</script>
You can also load modules via CDN, e.g.:
1<script type="module"> 2 import WinBox from "https://unpkg.com/winbox@0.2.82/src/js/winbox.js"; 3</script>
The ES6 modules are not minified. Please use your favored bundler or build tool for this purpose.
Overview
Constructor:
- new WinBox(title, options<key: value>) : winbox
Global methods:
- WinBox.new(title, options<key: value>) : winbox
- WinBox.stack() : Array<winbox>
Instance member methods:
- winbox.mount(src)
- winbox.unmount(dest)
- winbox.setUrl(string)
- winbox.setTitle(string)
- winbox.setIcon(url)
- winbox.move(x, y)
- winbox.resize(width, height)
- winbox.close(boolean)
- winbox.focus(state)
- winbox.blur(state)
- winbox.hide(state)
- winbox.show(state)
- winbox.minimize(state)
- winbox.maximize(state)
- winbox.fullscreen(state)
- winbox.restore(state)
- winbox.setBackground(string)
- winbox.addClass(name)
- winbox.removeClass(name)
- winbox.hasClass(name)
- winbox.toggleClass(name)
- winbox.addControl(options)
- winbox.removeControl(name)
Instance properties (readonly):
Instance properties (writable):
- winbox.x
- winbox.y
- winbox.width
- winbox.height
- winbox.top
- winbox.right
- winbox.bottom
- winbox.left
- winbox.minwidth
- winbox.minheight
- winbox.maxwidth
- winbox.maxheight
Instance state boolean properties (readonly):
Callback methods:
- winbox.oncreate
- winbox.onshow
- winbox.onhide
- winbox.onclose
- winbox.onfocus
- winbox.onblur
- winbox.onmove
- winbox.onresize
- winbox.onfullscreen
- winbox.onmaximize
- winbox.onminimize
- winbox.onrestore
Options
| Option | Values | Description |
| id | number | string | Set a unique id to the window. Used to define custom styles in css, query elements by context or just to identify the corresponding window instance. If no ID was set it will automatically create one for you. |
| index | number | Set the initial z-index of the window to this value (will be increased automatically when unfocused/focused). |
| title | string | The window title. |
| mount | HTMLElement | Mount an element (widget, template, etc.) to the window body. |
| html | string | Set the innerHTML of the window body. |
| url | string | Open URL inside the window (loaded via iframe). |
| width height | number | string | Set the initial width/height of the window (supports units "px" and "%"). |
| minwidth minheight | number | string | Set the minimal width/height of the window (supports units "px" and "%"). Should be at least the height of the window header title bar. |
| maxwidth maxheight | number | string | Set the maximum width/height of the window (supports units "px" and "%"). |
| autosize | boolean | Automatically size the window to fit the window contents. |
| overflow | boolean | Allow the window to move outside the viewport. |
| x y | number | string | Set the initial position of the window (supports: "right" for x-axis, "bottom" for y-axis, "center" for both, units "px" and "%" for both). |
| max | boolean | Automatically toggles the window into maximized state when created. |
| min | boolean | Automatically toggles the window into minimized state when created. |
| hidden | boolean | Automatically toggles the window into hidden state when created. |
| modal | boolean | Shows the window as modal. |
| top right bottom left | number | string | Set or limit the viewport of the window's available area (supports units "px" and "%"). Also used for custom splitscreen configurations. |
| background | string | Set the background of the window (supports all CSS styles which are also supported by the style-attribute "background", e.g. colors, transparent colors, hsl, gradients, background images) |
| border | number | Set the border width of the window (supports all the browsers css units). |
| icon | string | Make the titlebar icon visible and set the image source to this url. |
| class | string | Add one or more classnames to the window (multiple classnames as array or separated with whitespaces e.g. "class-a class-b"). Used to define custom styles in css, query elements by context (also within CSS) or just to tag the corresponding window instance. WinBox provides you some useful Built-in Control Classes to easily setup a custom configuration. |
| oncreate | function(options) | Callback triggered when the winbox element is being created. You can modify all these winbox options from this table passed as first parameter. |
| onmove | function(x, y) | Callback triggered when the window moves. |
| onresize | function(width, height) | Callback triggered when the window resizes. |
| onfullscreen | function() | Callback triggered when the window enters fullscreen. |
| onminimize | function() | Callback triggered when the window enters minimized mode. |
| onmaximize | function() | Callback triggered when the window enters maximize mode. |
| onrestore | function() | Callback triggered when the window returns to a windowed state from a Fullscreen, Minimized or Maximized state. |
| onhide | function() | Callback triggered when the window is hidden with win.hide() |
| onshow | function() | Callback triggered when the window is shown with win.show() |
| onclose | function(force) | Callbacks triggered when the window is closing. The keyword this inside the callback function refers to the corresponding WinBox instance. Note: the event 'onclose' will be triggered right before closing and stops closing when a callback was applied and returns a truthy value. |
| onfocus | function() | Callback triggered when a window goes into focused state. |
| onblur | function() | Callback triggered when a window lost the focused state. |
Create and Setup Window
Basic Window
When no
rootwas specified the window will append to thedocument.body.
1new WinBox("Window Title");
Alternatively:
1WinBox.new("Window Title");Alternatively:
1new WinBox({ title: "Window Title" });1var winbox = WinBox(); 2winbox.setTitle("Window Title");
Custom Root
The root is the unique element in a document where the window will append to. In most cases that is usually the
document.bodywhich is the default root. Multiple roots at the same time are just partially supported (they share the same viewport actually).
1new WinBox("Window Title", {
2 root: document.body
3});Custom Color
Supports all CSS styles which are also supported by the style-attribute "background", e.g. colors, rgba, hsl, gradients, background images.
1new WinBox("Custom Color", {
2 background: "#ff005d"
3});1var winbox = new WinBox("Custom Color"); 2winbox.setBackground("#ff005d");
Custom Border
Supports all units.
1new WinBox({
2 title: "Custom Border",
3 border: "1em"
4});You can also define multiple border values (the order is: top, right, bottom, left):
1new WinBox({
2 title: "Custom Border",
3 border: "0 1em 15px 1em"
4});Custom Titlebar Icon
Supports all datatypes which are also supported by the style-attribute "background-image", e.g. URL, base64 encoded data. The default icon size is 20 x 20 pixels.
1new WinBox({
2 title: "Custom Icon",
3 icon: "img/icon.svg"
4});1var winbox = new WinBox("Custom Icon"); 2winbox.setIcon("img/icon.svg");
See below in the style section to find out how to easily customize the titlebar icon style via css.
Custom Viewport
Define the available area (relative to the document) in which the window can move or could be resized (supports units "px" and "%").
1new WinBox("Custom Viewport", {
2 top: "50px",
3 right: "5%",
4 bottom: 50,
5 left: "5%"
6});Alternatively (but just support numbers!):
1var winbox = new WinBox("Custom Viewport"); 2 3winbox.top = 50; 4winbox.right = 200; 5winbox.bottom = 0; 6winbox.left = 200
Custom Position / Size
Supports keywords
"right"for x-axis,"bottom"for y-axis,"center"for both, unitspxand%also for both.
1new WinBox("Custom Viewport", {
2 x: "center",
3 y: "center",
4 width: "50%",
5 height: "50%"
6});1new WinBox("Custom Viewport", {
2 x: "right",
3 y: "bottom",
4 width: "200px",
5 height: "200px"
6});Alternatively (also supports same units and keywords as above):
1var winbox = new WinBox("Custom Viewport"); 2 3winbox.resize("50%", "50%") 4 .move("center", "center");
Alternatively (just support numeric values as px when directly assigned!):
1var winbox = new WinBox("Custom Viewport"); 2 3winbox.width = 200; 4winbox.height = 200; 5winbox.resize(); 6 7winbox.x = 100; 8winbox.y = 100; 9winbox.move();
In some cases you need to execute
.resize()before.move()to properly apply relative positions which is taking the windows size into account.
Overflow Window
Allow the window to move outside the viewport borders on left, right and bottom (default is "false").
1new WinBox({
2 title: "Overflow Window",
3 overflow: true
4});Modal Window
1new WinBox({
2 title: "Modal Window",
3 modal: true
4});Window Stack
The window stack gets you an ordered list of every created window which wasn't already closed. The last focused windows is placed as last entry in the Array.
1const a = new WinBox("A"); // window A gets focused 2const b = new WinBox("B"); // window B gets focused 3const c = new WinBox("C"); // window C gets focused 4a.focus(); // window A gets focused 5 6// get window stack ordered by focus history 7const stack = WinBox.stack(); // [B, C, A]
Themes
Feel free to create your own themes and share them with us.
You will find all themes here.
Load the corresponding css files (or use a bundler), e.g.:
1<head> 2 <link rel="stylesheet" href="dist/css/winbox.min.css"> 3 <link rel="stylesheet" href="dist/css/themes/modern.min.css"> 4 <script src="dist/js/winbox.min.js"></script> 5</head>
Just add the name of the theme via class:
1var winbox = new WinBox({
2 title: "Theme: Modern",
3 class: "modern"
4});Alternatively:
1var winbox = new WinBox("Theme: Modern"); 2winbox.addClass("modern");
You can change themes during the lifetime of the window.
Manage Window Content
Set innerHTML
Do not forget to sanitize any user inputs which is part of the html as this can lead to unintended XSS!
1new WinBox("Set innerHTML", {
2 html: "<h1>Lorem Ipsum</h1>"
3});Alternatively:
1var winbox = new WinBox("Set innerHTML"); 2winbox.body.innerHTML = "<h1>Lorem Ipsum</h1>";
Mount DOM (Cloned)
When cloning you can easily create multiple window instances of the same content in parallel.
1<div id="content"> 2 <h1>Lorem Ipsum</h1> 3 <p>Lorem ipsum [...]</p> 4</div>
1var node = document.getElementById("content");
2
3new WinBox("Mount DOM", {
4 mount: node.cloneNode(true)
5});Alternatively:
1var node = document.getElementById("content"); 2var winbox = new WinBox("Mount DOM"); 3 4winbox.mount(node.cloneNode(true));
Mount DOM (Singleton) + Auto-Unmount
A singleton is a unique fragment which can move inside the document. When creating multiple windows and mounting the same fragment to it, the fragment will leave the old window (see the method above for cloning).
This workaround is also compatible if you are using server-side rendering.
You can simply use a hidden backstore to hold contents, as well you can use any other strategy like a templating engine etc.
1<div id="backstore" style="display: none"> 2 <div id="content"> 3 <h1>Lorem Ipsum</h1> 4 <p>Lorem ipsum [...]</p> 5 </div> 6</div>
1var node = document.getElementById("content"); 2 3new WinBox("Mount DOM", { 4 mount: node 5});
Auto-Unmount is a helpful feature which automatically moves back the fragment to the backstore source when closing the window.
Alternatively:
1var node = document.getElementById("content"); 2var winbox = new WinBox("Mount DOM"); 3 4winbox.mount(node);
Explicit Unmount
1<div id="backstore" style="display: none"> 2 <div id="content"> 3 <h1>Lorem Ipsum</h1> 4 <p>Lorem ipsum [...]</p> 5 </div> 6</div> 7<div id="backstore-2" style="display: none"></div>
1var node = document.getElementById("content"); 2var winbox = new WinBox("Mount DOM");
Move fragment from hidden backstore to the window body:
1winbox.mount(node);
Move fragment back to the hidden backstore source:
1winbox.unmount();
Or move fragment to another destination:
1winbox.unmount(document.getElementById("backstore-2"));
Or just auto-unmount as default when closing:
1winbox.close();
Override default auto-unmount behavior when closing the window:
1new WinBox("Mount DOM", {
2 mount: node,
3 onclose: function(){
4 this.unmount(document.getElementById("backstore-2"));
5 }
6});Manual Mount Contents
Feel free to use the winbox.body directly:
1var node = document.getElementById("content"); 2var winbox = new WinBox("Mount DOM"); 3 4winbox.body.appendChild(node);
Or delegate it as a root to your templating engine, e.g.:
1Mikado(template).mount(winbox.body).render(data);
Open URI / URL
Do not forget to sanitize any user inputs when it is part of the url as this can lead to unintended XSS!
The onload callback is optionally.
1new WinBox("Open URL", {
2 url: "https://wikipedia.com",
3 onload: function(){ /* extern page loaded */}
4});You can use every URI scheme which is supported by
srcattribute, e.g. URL, image or video, base64 encoded data.
1var winbox = new WinBox("Open URL"); 2winbox.setUrl("https://wikipedia.com", function(){ 3 /* extern page loaded */ 4});
The WinBox Window Instance
1var winbox = new WinBox();
2
3console.log("Window ID:", winbox.id);
4console.log("Window Index:", winbox.index);
5console.log("Current Maximize State:", winbox.max);
6console.log("Current Minimize State:", winbox.min);
7console.log("Current Fullscreen State:", winbox.full);
8console.log("Current Hidden State:", winbox.hidden);
9console.log("Current Focused State:", winbox.focused);1var winbox = new WinBox(); 2 3winbox.width = 200; 4winbox.height = 200; 5winbox.resize(); 6 7console.log("Current Width:", winbox.width); 8console.log("Current Height:", winbox.height);
1var winbox = new WinBox(); 2 3winbox.x = 100; 4winbox.y = 100; 5winbox.move(); 6 7console.log("Current Position X:", winbox.x); 8console.log("Current Position Y:", winbox.y);
1var winbox = new WinBox(); 2 3winbox.top = 50; 4winbox.right = 50; 5winbox.bottom = 50; 6winbox.left = 50; 7 8// update window if needed: 9winbox.resize().move(); 10 11console.log("Current Viewport Top:", winbox.top); 12console.log("Current Viewport Right:", winbox.right); 13console.log("Current Viewport Bottom:", winbox.bottom); 14console.log("Current Viewport Left:", winbox.left);
The window body acts like the document.body and has a scroll pane:
1var winbox = new WinBox(); 2winbox.body.innerHTML = "<h1>Lorem Ipsum</h1>";
Get the DOM element from the window outer frame:
1var winbox = new WinBox(); 2var root = winbox.window;
You also can get the window element by DOM id:
1var winbox = new WinBox(); 2var root = document.getElementById(winbox.id);
The window element points to the window most outer root element which also holds the window control and state classes:
You can access and modify the window DOM element directly:
1const root = winbox.window; 2const hidden = root.classList.contains("hide"); 3const focused = root.classList.contains("focus"); 4root.classList.remove("modal"); 5root.classList.add("my-theme"); 6root.classList.toggle("my-toggle");
Or as an equivalent to the example above by using the WinBox built-in methods respectively:
1const hidden = winbox.hasClass("hide"); 2const focused = winbox.hasClass("focus"); 3winbox.removeClass("modal"); 4winbox.addClass("my-theme"); 5winbox.toggleClass("my-toggle");
You can grab the winbox instance from the window outer frame DOM element:
1var winbox = new WinBox(); 2// assume you have a DOM reference to the winbox window: 3var window_element = document.getElementById(winbox.id); 4// grab corresponding instance from window element: 5winbox = window_element.winbox;
Controls
1var winbox = new WinBox();
Focus a window (bring up to front):
1winbox.focus(); 2winbox.focus(true); 3winbox.blur(false);
1winbox.blur(); 2winbox.blur(true); 3winbox.focus(false);
Set the minimized state of a window:
1winbox.minimize(); 2winbox.minimize(true); 3winbox.minimize(false);
Set the maximized state of a window:
1winbox.maximize(); 2winbox.maximize(true); 3winbox.maximize(false);
Set the fullscreen state of a window:
1winbox.fullscreen(); 2winbox.fullscreen(true); 3winbox.fullscreen(false);
Restore the state of a window:
1winbox.restore();
1winbox.hide(); 2winbox.hide(true); 3winbox.show(false);
Show a specific hidden window:
1winbox.show(); 2winbox.show(true); 3winbox.hide(false);
1winbox.close();
Close and destroy a window depending on custom conditional (e.g. by a confirmation status):
1winbox.close(false || true);
Chaining Methods
1var winbox = WinBox(); 2 3winbox.setTitle("Title") 4 .setBackground("#fff") 5 .resize("50%", "50%") 6 .move("center", "center") 7 .mount(document.getElementById("content"));
When using "center" as position you need to call
.resize()before.move().
Callbacks
You can assign callbacks via the option payload when creating a window.
The keyword
thisin your callback function refers to the corresponding WinBox Instance.
1var winbox = WinBox({ 2 oncreate: function(options){ 3 options.autosize = true; 4 }, 5 onfocus: function(){ 6 this.setBackground("#fff"); 7 }, 8 onblur: function(){ 9 this.setBackground("#999"); 10 }, 11 onresize: function(width, height){ 12 console.log("width:", width, "height:", height); 13 }, 14 onfullscreen: function(){ 15 this.setBackground("#666"); 16 }, 17 onminimize: function(){ 18 this.setBackground("#999"); 19 }, 20 onmaximize: function(){ 21 this.setBackground("#AAA"); 22 }, 23 onrestore: function(){ 24 this.setBackground("#DDD"); 25 }, 26 onmove: function(x, y){ 27 console.log("x:", x, "y:", y); 28 }, 29 onclose: function(force){ 30 // return "true" to skip the closing 31 // return "false" to allow closing 32 // use delegated force parameter optionally 33 return !confirm("Close window?"); 34 } 35});
The "onclose" callback
The event
onclosewill be triggered right before closing and stops closing when a callback was applied and returns a truthy value.
Within your callback function just return true to stops the closing or return false to perform closing as default.
1new WinBox({ 2 onclose: function(){ 3 // return "true" to skip the closing 4 // return "false" to allow closing 5 if(do_some_checks()){ 6 return true; 7 } 8 } 9});
The force parameter from the winbox.close(boolean) will be delegated to your callback function as the first parameter. You need to handle the "force" state in your callback function.
1var winbox = WinBox({ 2 onclose: function onclose(force){ 3 // use delegated force parameter optionally 4 return !force && !confirm("Close window?"); 5 } 6});
Close the window and execute callback as default (will show the prompt from example above):
1winbox.close();
Force closing the window (does not show the prompt from example above):
1winbox.close(true);
Use Control Classes
WinBox provides you some built-in control classes you can pass when creating a window instance.
All control classes from this list could be added or removed during lifetime of the window (after creation). State classes like
max,min,full,hiddenandfocuscould not be changed manually! For this purpose use the WinBox member methods accordingly e.g.maximize(),minimize(),hide().
| Classname | Description |
|---|---|
| no-animation | Disables the windows transition animation |
| no-shadow | Disables the windows drop shadow |
| no-header | Hide the window header incl. title and toolbar |
| no-min | Hide the minimize icon |
| no-max | Hide the maximize icon |
| no-full | Hide the fullscreen icon |
| no-close | Hide the close icon |
| no-resize | Disables the window resizing capability |
| no-move | Disables the window moving capability |
Without the header the user isn't able to move the window frame. It may be useful for creating fixed popups.
Pass in classnames when creating the window to apply behaviour:
1const winbox = WinBox({ 2 class: [ "no-min", "no-max", "no-full", "no-resize", "no-move" ] 3});
The example above is a good start to create classical popups.
Alternatively you can use a whitespace separated string:
1const winbox = WinBox({ 2 class: "no-min no-max no-full no-resize no-move" 3});
You can add or remove all control classes from above along the window's lifetime:
1const winbox = WinBox(); 2 3winbox.addClass("no-resize") 4 .addClass("no-move");
1winbox.removeClass("no-resize") 2 .removeClass("no-move");
1winbox.toggleClass("no-resize") 2 .toggleClass("no-move");
1const state = winbox.hasClass("no-resize") && 2 winbox.hasClass("no-move");
Custom Splitscreen
Use the viewport limit to define your own splitscreen areas, e.g. for a simple vertical split:
1new WinBox("Split Left", {
2 right: "50%"
3});
4
5new WinBox("Split Right", {
6 left: "50%"
7});Same way you can also define custom sizes and positions for each split as well as complex grids, e.g.:
1new WinBox("Split Top-Left", { right: "66%", bottom: "50%", max: true });
2new WinBox("Split Bottom-Left", { right: "66%", top: "50%", max: true });
3
4new WinBox("Split Middle", { left: "34%", right: "34%", max: true });
5
6new WinBox("Split Top-Right", { left: "66%", bottom: "50%", max: true });
7new WinBox("Split Bottom-Right", { left: "66%", top: "50%", max: true });The splitscreen from above will look like this grid:
---------------------------------------------
| | | |
| | | |
| Top Left | | Top Right |
| | | |
| | | |
--------------- Middle ----------------
| | | |
| | | |
| Bottom Left | | Bottom Right |
| | | |
| | | |
---------------------------------------------
You can set the values for the viewport dynamically, doing this makes it possible to size the grid dynamically and also change the grid schema.
Custom Controls
This example will add a custom control button .wb-like to the window heading toolbar along some CSS for icon styling:
1.wb-like { 2 background-size: 20px auto; 3} 4.wb-like.active { 5 background-image: url(demo/heart-filled.svg) !important; 6}
Attach a control to the window toolbar:
1winbox.addControl({ 2 // the position index 3 index: 1, 4 // classname to apply styling 5 class: "wb-like", 6 // icon url when not specified via classname 7 image: "demo/heart.svg", 8 // click listener 9 click: function(event, winbox){ 10 // the winbox instance will be passed as 2nd parameter 11 console.log(winbox.id); 12 // "this" refers to the button which was clicked: 13 this.classList.toggle("active"); 14 } 15});
Remove a control from the window toolbar:
1winbox.removeControl("wb-like") 2 .removeControl("wb-min");
Custom Template (Layout)
You can fully customize the WinBox window layout by providing a custom template via the config during creation. This way you can add new elements to the window or re-arrange them.
This example will add a control button .wb-custom to the window toolbar by using a custom template along some CSS:
1.wb-custom { 2 background-image: url(demo/icon-github.svg); 3 background-size: 17px auto; 4}
Create by using a custom template:
1const template = document.createElement("div"); 2template.innerHTML = ` 3 <div class=wb-header> 4 <div class=wb-control> 5 <span class=wb-custom></span> 6 <span class=wb-close></span> 7 </div> 8 <div class=wb-drag></div> 9 </div> 10 <div class=wb-body></div> 11`; 12 13new WinBox("Custom Template", { template });
The
.wb-dragelement needs to be existing when the user should be able to move the window by dragging the heading toolbar.
Customize Window
Additionally, take a look into the themes folder to get some ideas how to customize the window.
The window boilerplate:
Hide or disable specific icons:
1.wb-min { display: none } 2.wb-full { display: none } 3.wb-max { display: none } 4.wb-close { display: none }
Modify a specific icon:
1.wb-max { 2 background-image: url(src/img/max.png); 3 background-position: center; 4 background-size: 15px auto; 5}
Use black standard icons (useful for bright backgrounds):
1.wb-control { filter: invert(1) }
Modify or disable resizing areas on the window borders:
1/* north */ 2.wb-n { display: none } 3 4/* east */ 5.wb-e { display: none } 6 7/* south */ 8.wb-s { display: none } 9 10/* west */ 11.wb-w { display: none } 12 13/* north-west */ 14.wb-nw { display: none } 15 16/* north-east */ 17.wb-ne { display: none } 18 19/* south-west */ 20.wb-sw { display: none } 21 22/* south-east */ 23.wb-se { display: none }
Modify or disable the window drop shadow:
1.winbox { box-shadow: none }
Style the header title:
1.wb-title { font-size: 12px }
Style the titlebar icon:
1.wb-icon { 2 width: 35px; 3 background-size: 35px 35px; 4}
Style the window background (frame):
1.winbox { 2 background: linear-gradient(90deg, #ff00f0, #0050ff); 3 border-radius: 12px 12px 0 0; 4}
Style the body of a window element and set the frame border:
1.wb-body { 2 /* the width of window frame border: */ 3 margin: 4px; 4 color: #fff; 5 background: #131820; 6}
The margin of
.wb-bodycorresponds to the width of the window border.
Apply styles when window is in "minimized" state:
1.winbox { 2 border-radius: 10px; 3} 4.winbox.min { 5 border-radius: 0; 6} 7.winbox.min .windbox-title { 8 font-size: 12px; 9}
Apply styles when window is NOT in "minimized" state:
1.winbox:not(.min) { 2 /* apply styles */ 3}
Apply styles when window is in "maximized" state:
1.winbox { 2 border-radius: 10px; 3} 4.winbox.max { 5 border-radius: 0; 6} 7.winbox.max .wb-max { 8 opacity: 0.5; 9}
Apply styles when window is NOT in "maximized" state:
1.winbox:not(.max) { 2 /* apply styles */ 3}
Apply styles when window is in "fullscreen" state:
1.wb-body:fullscreen { 2 /* apply styles */ 3}
Apply styles when window is in "focus" state:
1.winbox { 2 background: #999; 3} 4.winbox.focus { 5 background: #0050ff; 6} 7.winbox .wb-control { 8 display: none; 9} 10.winbox.focus .wb-control { 11 display: block; 12}
Apply styles when window is NOT in "focus" state (the same logic from example above, but shorter):
1.winbox:not(.focus) { 2 background: #999; 3} 4.winbox:not(.focus) .wb-control { 5 display: none; 6}
Apply styles when window is in "modal" state:
1.winbox.modal .wb-close { display: none }
Customize the modal background overlay:
1.winbox.modal:after { 2 background: #0d1117; 3 opacity: 0.5; 4 animation: none; 5}
Style Scrollbars
1.wb-body::-webkit-scrollbar { 2 width: 12px; 3} 4.wb-body::-webkit-scrollbar-track { 5 background: transparent; 6} 7.wb-body::-webkit-scrollbar-thumb { 8 border-radius: 10px; 9 background: #263040; 10} 11.wb-body::-webkit-scrollbar-thumb:window-inactive { 12 background: #181f2a; 13} 14.wb-body::-webkit-scrollbar-corner { 15 background: transparent; 16}
Useful Hints
Often you need to hide specific content parts when it was mounted to a window or hiding when NOT inside a window:
Now you can add the two classes "wb-hide" and "wb-show" to any element to control visibility between the two states "inside" and "outside" a window:
1<body> 2 <main id="content"> 3 <header class="wb-hide">Hide this header when in windowed mode</header> 4 <section> 5 <!-- page contents --> 6 </section> 7 <footer class="wb-show">Hide this footer when NOT in windowed mode</footer> 8 </main> 9</body>
The display property when using "wb-show" might not fit your needs. Please change this css class definition to your desired display-state accordingly.
1new WinBox({
2 mount: document.getElementById("content")
3});Best Practices
- Use a non-scrolling body element to get the best user experience on mobile devices.
- Or provide an alternative view strategy for mobile devices, e.g. when the device is a touch device then open a classical app view. If a mouse pointer is available, then mount this view to the WinBox window. Also, you can place a switch button in your application where the user can also toggle between these two modes.
WinBox on Angular application
Step 1: Install WinBox library
npm i winbox
Step 2: Install WinBox types
npm i @types/winbox --save-dev
Step 3: Import WinBox in a component
1import { Component } from '@angular/core';
2import 'winbox';
3declare const WinBox: WinBox.WinBoxConstructor;
4
5@Component({
6 selector: 'my-app',
7 template: '<button (click)="openWindow()">Open Window</button>'
8})
9export class AppComponent {
10 openWindow() {
11 WinBox.new();
12 }
13}WinBox on Vue application
https://github.com/wobsoriano/vue-winbox
It uses the native teleport component in Vue 3 and recommends https://github.com/LinusBorg/vue-simple-portal for Vue 2 users.
WinBox on React application
https://github.com/rickonono3/react-winbox
A React controlled component for WinBox.js, with full Reactful props and state. Includes all configurations of WinBox.js by using React component props.
Custom Builds
Go to the root directory of WinBox and run:
1npm install
Perform a build:
1npm run build
The final build is located in the dist/ folder.
Copyright 2021-2023 Thomas Wilkerling, Hosted by Nextapps GmbH
Released under the Apache 2.0 License
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
0 existing vulnerabilities detected
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
Found 1/29 approved changesets -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 2 are checked with a SAST tool
Score
3.5
/10
Last Scanned on 2025-07-07
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More