-
Notifications
You must be signed in to change notification settings - Fork 6
/
vanui.html
457 lines (426 loc) · 69.3 KB
/
vanui.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
<!DOCTYPE html>
<html lang="en"><head>
<link rel="icon" href="/logo.svg">
<title>VanUI - A Collection of Grab 'n Go Reusable UI Components for VanJS</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
@font-face {
font-family: 'Poppins';
font-style: normal;
font-weight: 400;
src: url(https://fonts.gstatic.com/s/poppins/v20/pxiEyp8kv8JHgFVrJJfedw.ttf) format('truetype');
}
</style>
<link rel="stylesheet" href="/code/w3-v1.css">
<link rel="stylesheet" href="/code/prism-v1.css">
<link rel="stylesheet" href="/vanjs.css">
</head>
<body class="line-numbers" data-prismjs-copy="📋">
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-Q0NB75RY7E"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-Q0NB75RY7E');
</script>
<script type="text/javascript" src="/code/prism-v1.js" defer></script>
<!-- Sidebar/menu -->
<nav class="w3-sidebar w3-red w3-collapse w3-top w3-large w3-padding" style="z-index:3;width:280px;font-weight:bold;" id="mySidebar"><br>
<a href="javascript:void(0)" onclick="w3_close()" class="w3-button w3-hide-large w3-display-topleft" style="width:100%;font-size:22px">Close Menu</a>
<div class="w3-container">
<h1 class="w3-padding-16 w3-xxxlarge">
<img src="/logo.svg" alt="VanJS" width="192px" height="192px">
</h1>
</div>
<div id="nav" class="w3-bar-block"><a href="/" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">Home</a><a href="/start" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">Getting Started</a><a href="/tutorial" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">Tutorial</a><a href="/demo" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">VanJS by Example</a><a href="/convert" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">HTML/MD to VanJS</a><a href="/vanui" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white current">VanUI</a><a href="/minivan" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">Mini-Van</a><a href="/ssr" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">SSR & Hydration</a><a href="/x" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">X</a><a href="/advanced" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">Advanced Topics</a><a href="/media" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">Media Coverage</a><a href="/about" onclick="w3_close()" class="w3-bar-item w3-button w3-hover-white">About</a></div>
</nav>
<!-- Top menu on small screens -->
<header class="w3-container w3-top w3-hide-large w3-red w3-xlarge w3-padding">
<a href="javascript:void(0)" class="w3-button w3-red w3-margin-right" onclick="w3_open()">☰</a>
<span id="title-bar">VanUI</span>
</header>
<!-- Overlay effect when opening sidebar on small screens -->
<div class="w3-overlay w3-hide-large" onclick="w3_close()" style="cursor:pointer" title="close side menu" id="myOverlay"></div>
<!-- !PAGE CONTENT! -->
<div class="w3-main" style="margin-left:300px;">
<div id="page">
<div id="content"><h1 class="w3-xxlarge"><strong>VanUI</strong>: A Collection of Grab 'n Go Reusable Utility and UI Components for VanJS</h1><p>🙏 Feedback and contribution are welcome and greatly appreciated! (<a href="https://github.com/vanjs-org/van/tree/main/components" class="w3-hover-opacity">source code</a>)</p><h2 class="w3-xxlarge w3-text-red" id="installation"><a class="self-link" href="#installation">Installation</a></h2><hr style="width:50px;border:5px solid red" class="w3-round"><h3 class="w3-large w3-text-red" id="via-npm"><a class="self-link" href="#via-npm">Via NPM</a></h3><p>The library is published as NPM package <a href="https://www.npmjs.com/package/vanjs-ui" class="w3-hover-opacity">vanjs-ui</a>. Run the following command to install the package:</p><pre><code class="language-shell">npm install vanjs-ui
</code></pre><p>To use the NPM package, add this line to your script:</p><pre><code class="language-js">import { <components you want to import> } from "vanjs-ui"
</code></pre><h3 class="w3-large w3-text-red" id="via-a-script-tag"><a class="self-link" href="#via-a-script-tag">Via a Script Tag</a></h3><p>Alternatively, you can import <strong>VanUI</strong> from CDN via a <code class="symbol"><script type="text/javascript"></code> tag:</p><pre><code class="language-html"><script type="text/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/van-ui.nomodule.min.js"></script>
</code></pre><p><code class="symbol">https://cdn.jsdelivr.net/npm/[email protected]/dist/van-ui.nomodule.js</code> can be used for the non-minified version.</p><p>Note that: <strong>VanJS</strong> needs to be imported via a <code class="symbol"><script type="text/javascript"></code> tag for <strong>VanUI</strong> to work properly.</p><p>Try on jsfiddle: <a href="https://jsfiddle.net/1brxdjh9/" class="w3-hover-opacity">Modal</a>, <a href="https://jsfiddle.net/cb9rs5yu/" class="w3-hover-opacity">MessageBoard</a>.</p><h3 class="w3-large w3-text-red" id="typescript-support-for-script-tag-integration"><a class="self-link" href="#typescript-support-for-script-tag-integration">TypeScript Support for Script Tag Integration</a></h3><p>To get TypeScript support for <code class="symbol"><script></code> tag integration, download <a href="https://vanjs.org/autodownload?file=van-ui.d.ts" class="w3-hover-opacity"><code class="symbol">van-ui.d.ts</code></a> and add the code like following at the top of your <code class="symbol">.ts</code> file:</p><pre><code class="language-ts">import type { Modal as ModalType } from "./van-ui.d.ts"
declare const Modal: typeof ModalType
</code></pre><h2 class="w3-xxlarge w3-text-red" id="documentation"><a class="self-link" href="#documentation">Documentation</a></h2><hr style="width:50px;border:5px solid red" class="w3-round"><p>The following components have been implemented so far:</p><ul><li>Utility components:<ul><li><a href="#await" class="w3-hover-opacity">Await</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/await?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">preview</a>)</li></ul></li><li>UI components:<ul><li><a href="#modal" class="w3-hover-opacity">Modal</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/modal?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">preview</a>)</li><li><a href="#tabs" class="w3-hover-opacity">Tabs</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/tabs?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">preview</a>)</li><li><a href="#message" class="w3-hover-opacity">MessageBoard</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/message?file=/src/main.ts" class="w3-hover-opacity">preview</a>)</li><li><a href="#tooltip" class="w3-hover-opacity">Tooltip</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/tooltip?file=/src/main.ts:1,1" class="w3-hover-opacity">preview</a>)</li><li><a href="#toggle" class="w3-hover-opacity">Toggle</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/toggle?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">preview</a>)</li><li><a href="#optiongroup" class="w3-hover-opacity">OptionGroup</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/option-group?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">preview</a>)</li><li><a href="#banner" class="w3-hover-opacity">Banner</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/banner?file=/src/main.ts:1,1" class="w3-hover-opacity">preview</a>)</li><li><a href="#floatingwindow" class="w3-hover-opacity">FloatingWindow</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/window?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">preview</a>)</li><li><span style="color:red; padding-right: 0.3rem;"><strong>New!</strong></span><a href="#choose" class="w3-hover-opacity">choose</a> (<a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/choose?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">preview</a>)</li></ul></li></ul><h3 class="w3-large w3-text-red" id="await"><a class="self-link" href="#await">Await</a></h3><p><em>Author: <a href="https://github.com/Hunter-Gu" class="w3-hover-opacity">@Hunter-Gu</a></em></p><p><code class="symbol">Await</code> is a utility component that helps you build UI components based on asynchronous data (i.e.: a JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="w3-hover-opacity"><code class="symbol">Promise</code></a> object).</p><h4 class="w3-medium w3-text-red" id="signature"><a class="self-link" href="#signature">Signature</a></h4><pre><code class="language-js">Await({
value, // A `Promise` object for asynchronous data
container, // The container of the result. Default `div`
Loading, // What to render when the data is being loaded
Error, // What to render when error occurs
}, children) => <The created UI element>
</code></pre><p>The <code class="symbol">children</code> parameter (type: <code class="symbol">(data: T) => ValidChildDomValue</code>) is a function that takes the resolved data as input and returns a valid child DOM value (<code class="symbol">Node</code>, primitives, <code class="symbol">null</code> or <code class="symbol">undefined</code>), used to indicate what to render after the data is loaded.</p><h4 class="w3-medium w3-text-red" id="examples"><a class="self-link" href="#examples">Examples</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/await?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><p>Example 1 (fetching the number of GitHub stars):</p><pre><code class="language-ts">const Example1 = () => {
const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
const fetchWithDelay = (url: string, waitMs: number) =>
sleep(waitMs).then(() => fetch(url)).then(r => r.json())
const fetchStar = () =>
fetchWithDelay("https://api.github.com/repos/vanjs-org/van", 1000)
.then(data => data.stargazers_count)
const data = van.state(fetchStar())
return [
() => h2(
"Github Star: ",
Await({
value: data.val, container: span,
Loading: () => "🌀 Loading...",
Error: () => "🙀 Request failed.",
}, starNumber => `⭐️ ${starNumber}!`)
),
() => Await({
value: data.val,
Loading: () => '',
}, () => button({onclick: () => (data.val = fetchStar())}, "Refetch")),
]
}
</code></pre><p>Example 2 (parallel <code class="symbol">Await</code>):</p><pre><code class="language-ts">const Example2 = () => {
const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
const loadNumber = () =>
sleep(Math.random() * 1000).then(() => Math.floor(Math.random() * 10))
const a = van.state(loadNumber()), b = van.state(loadNumber())
return [
h2("Parallel Await"),
() => {
const sum = van.derive(() => Promise.all([a.val, b.val]).then(([a, b]) => a + b))
return Await({
value: sum.val,
Loading: () => div(
Await({value: a.val, Loading: () => "🌀 Loading a..."}, () => "Done"),
Await({value: b.val, Loading: () => "🌀 Loading b..."}, () => "Done"),
),
}, sum => "a + b = " + sum)
},
p(button({onclick: () => (a.val = loadNumber(), b.val = loadNumber())}, "Reload")),
]
}
</code></pre><h4 class="w3-medium w3-text-red" id="property-reference"><a class="self-link" href="#property-reference">Property Reference</a></h4><ul><li><code class="symbol">value</code>: Type <code class="symbol">Promise</code>. Required. The asynchronous data that the result UI element is based on.</li><li><code class="symbol">container</code>: Type <code class="symbol">TagFunction<Element></code>. Default <code class="symbol">div</code> (<code class="symbol">van.tags.div</code>). Optional. The type of the wrapper HTML element for the result.</li><li><code class="symbol">Loading</code>: Type <code class="symbol">() => ValidChildDomValue</code>. Optional. If specified, indicates what to render when the asynchronous data is being loaded.</li><li><code class="symbol">Error</code>: Type <code class="symbol">(reason: Error) => ValidChildDomValue</code>. Optional. If specified, indicates what to render when error occurs while fetching the asynchronous data.</li></ul><h3 class="w3-large w3-text-red" id="modal"><a class="self-link" href="#modal">Modal</a></h3><p>Creates a modal window on top of the current page.</p><h4 class="w3-medium w3-text-red" id="signature-1"><a class="self-link" href="#signature-1">Signature</a></h4><pre><code class="language-js">Modal({...props}, ...children) => <The created modal window>
</code></pre><h4 class="w3-medium w3-text-red" id="examples-1"><a class="self-link" href="#examples-1">Examples</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/modal?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><p>Example 1:</p><pre><code class="language-ts">const closed = van.state(false)
van.add(document.body, Modal({closed},
p("Hello, World!"),
div({style: "display: flex; justify-content: center;"},
button({onclick: () => closed.val = true}, "Ok"),
),
))
</code></pre><p>Example 2:</p><pre><code class="language-ts">const closed = van.state(false)
const formDom = form(
div(input({type: "radio", name: "lang", value: "Zig", checked: true}), "Zig"),
div(input({type: "radio", name: "lang", value: "Rust"}), "Rust"),
div(input({type: "radio", name: "lang", value: "Kotlin"}), "Kotlin"),
div(input({type: "radio", name: "lang", value: "TypeScript"}), "TypeScript"),
div(input({type: "radio", name: "lang", value: "JavaScript"}), "JavaScript"),
)
const onOk = () => {
const lang = (<HTMLInputElement>formDom.querySelector("input:checked")).value
alert(lang + " is a good language 😀")
closed.val = true
}
van.add(document.body, Modal({closed, blurBackground: true},
p("What's your favorite programming language?"),
formDom,
p({style: "display: flex; justify-content: space-evenly;"},
button({onclick: onOk}, "Ok"),
button({onclick: () => closed.val = true}, "Cancel"),
)
))
</code></pre><h4 class="w3-medium w3-text-red" id="property-reference-1"><a class="self-link" href="#property-reference-1">Property Reference</a></h4><ul><li><code class="symbol">closed</code>: Type <code class="symbol">State<boolean></code>. Required. A <code class="symbol">State</code> object used to close the created modal window. Basically, setting <code class="symbol">closed.val = true</code> will close the created modal window. You can also subscribe the closing event of the modal window via <a href="https://vanjs.org/tutorial#api-derive" class="w3-hover-opacity"><code class="symbol">van.derive</code></a>.</li><li><code class="symbol">backgroundColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"rgba(0,0,0,.5)"</code>. Optional. The color of the background overlay when the modal is activated.</li><li><code class="symbol">blurBackground</code>: Type <code class="symbol">boolean</code>. Default <code class="symbol">false</code>. Optional. Whether to blur the background.</li><li><code class="symbol">backgroundClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the background overlay. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">backgroundStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the background overlay.</li><li><code class="symbol">modalClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the created modal element. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">modalStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the created modal element.</li></ul><h3 class="w3-large w3-text-red" id="tabs"><a class="self-link" href="#tabs">Tabs</a></h3><p>Creates a tab-view for tabs specified by the user.</p><h4 class="w3-medium w3-text-red" id="signature-2"><a class="self-link" href="#signature-2">Signature</a></h4><pre><code class="language-js">Tabs({...props}, tabContents) => <The created tab-view>
</code></pre><p>The <code class="symbol">tabContents</code> parameter is an object whose keys are the titles of the tabs and values (type: <code class="symbol">ChildDom</code>) are the DOM element(s) for the tab contents.</p><h4 class="w3-medium w3-text-red" id="example"><a class="self-link" href="#example">Example</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/tabs?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><pre><code class="language-ts">van.add(document.body, Tabs(
{
style: "max-width: 500px;",
tabButtonActiveColor: "white",
tabButtonBorderStyle: "none",
tabButtonRowStyleOverrides: {
"padding-left": "12px",
},
},
{
Home: p(
"Welcome to ", b("VanJS"), " - the smallest reactive UI framework in the world.",
),
"Getting Started": [
p("To install the ", b("VanJS"), " NPM package, run the line below:"),
pre(code("npm install vanjs-core")),
],
About: p(
"The author of ", b("VanJS"), " is ",
a({href: "https://github.com/Tao-VanJS"}, " Tao Xin"), "."
),
},
))
</code></pre><h4 class="w3-medium w3-text-red" id="property-reference-2"><a class="self-link" href="#property-reference-2">Property Reference</a></h4><ul><li><code class="symbol">activeTab</code>: Type <code class="symbol">State<string></code>. Optional. If specified, you can activate a tab via the specified <code class="symbol">State</code> object with <code class="symbol">activeTab.val = "<tab title>"</code>, and subscribe to the changes of active tab via <a href="https://vanjs.org/tutorial#api-derive" class="w3-hover-opacity"><code class="symbol">van.derive</code></a>.</li><li><code class="symbol">resultClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the result DOM element. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">style</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">style</code> property of the result DOM element.</li><li><code class="symbol">tabButtonRowColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#f1f1f1"</code>. Optional. The background color of the container of tab buttons.</li><li><code class="symbol">tabButtonBorderStyle</code>: Type <code class="symbol">string</code>. Default <code class="symbol">1px solid #000</code>. Optional. The style of borders between tab buttons.</li><li><code class="symbol">tabButtonHoverColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#ddd"</code>. Optional. The color when the tab button is hovered.</li><li><code class="symbol">tabButtonActiveColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#ccc"</code>. Optional. The color of the tab button for the currently active tab.</li><li><code class="symbol">transitionSec</code>: Type <code class="symbol">number</code>. Default <code class="symbol">0.3</code>. Optional. The duration of the transition when tab buttons change color.</li><li><code class="symbol">tabButtonRowClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the container of tab buttons. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">tabButtonRowStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the container of tab buttons.</li><li><code class="symbol">tabButtonClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. The <code class="symbol">class</code> attribute of tab buttons. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">tabButtonStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for tab buttons. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">tabContentClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. The <code class="symbol">class</code> attribute of tab contents. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">tabContentStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for tab contents.</li></ul><h3 class="w3-large w3-text-red" id="messageboard"><a class="self-link" href="#messageboard">MessageBoard</a></h3><p>Creates a message board to show messages on the screen.</p><h4 class="w3-medium w3-text-red" id="signature-3"><a class="self-link" href="#signature-3">Signature</a></h4><p>To create a message board:</p><pre><code class="language-js">const board = new MessageBoard({...props})
</code></pre><p>Then you can show messages with <code class="symbol">show</code> method:</p><pre><code class="language-js">board.show({...props}) => <The created DOM node for the message, which is also appended to the message board>
</code></pre><p>Optionally, you can remove the DOM node of the message board with <code class="symbol">remove</code> method:</p><pre><code class="language-js">board.remove()
</code></pre><h4 class="w3-medium w3-text-red" id="examples-2"><a class="self-link" href="#examples-2">Examples</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/message?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><pre><code class="language-ts">const board = new MessageBoard({top: "20px"})
const example1 = () => board.show({message: "Hi!", durationSec: 1})
const example2 = () => board.show(
{message: ["Welcome to ", a({href: "https://vanjs.org/", style: "color: #0099FF"}, "🍦VanJS"), "!"], closer: "❌"})
const closed = van.state(false)
const example3 = () => {
closed.val = false
board.show({message: "Press ESC to close this message", closed})
}
document.addEventListener("keydown", e => e.key === "Escape" && (closed.val = true))
</code></pre><h4 class="w3-medium w3-text-red" id="property-reference-3"><a class="self-link" href="#property-reference-3">Property Reference</a></h4><p>Message board properties:</p><ul><li><code class="symbol">top</code>: Type <code class="symbol">string</code>. Optional. The <code class="symbol">top</code> CSS property of the message board.</li><li><code class="symbol">bottom</code>: Type <code class="symbol">string</code>. Optional. The <code class="symbol">bottom</code> CSS property of the message board. Exactly one of <code class="symbol">top</code> and <code class="symbol">bottom</code> should be specified.</li><li><code class="symbol">backgroundColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#333D"</code>. Optional. The background color of the messages shown on the message board.</li><li><code class="symbol">fontColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"white"</code>. Optional. The font color of the messages shown on the message board.</li><li><code class="symbol">fadeOutSec</code>: Type <code class="symbol">number</code>. Default <code class="symbol">0.3</code>. Optional. The duration of the fade out animation when messages are being closed.</li><li><code class="symbol">boardClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the message board. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">boardStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the message board.</li><li><code class="symbol">messageClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the message shown on the message board. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">messageStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the message shown on the message board.</li><li><code class="symbol">closerClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the message closer. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">closerStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the message closer.</li></ul><p>Message properties:</p><ul><li><code class="symbol">message</code>: Type <code class="symbol">ChildDom</code>. Required. One <code class="symbol">ChildDom</code> or multiple <code class="symbol">ChildDom</code> as an <code class="symbol">Array</code> for the message we want to show.</li><li><code class="symbol">closer</code>: Type <code class="symbol">ChildDom</code>. Optional. If specified, we will render a closer DOM node with one <code class="symbol">ChildDom</code> or multiple <code class="symbol">ChildDom</code>s as an <code class="symbol">Array</code> which can be clicked to close the shown message.</li><li><code class="symbol">durationSec</code>: Type <code class="symbol">number</code>. Optional. If specified, the shown message will be automatically closed after <code class="symbol">durationSec</code> seconds.</li><li><code class="symbol">closed</code>: Type <code class="symbol">State<boolean></code>. Optional. If specified, the shown message can be closed via the <code class="symbol">closed</code><code class="symbol">State</code> object with <code class="symbol">closed.val = true</code>. You can also subscribe the closing event of the message via <a href="https://vanjs.org/tutorial#api-derive" class="w3-hover-opacity"><code class="symbol">van.derive</code></a>.</li></ul><h3 class="w3-large w3-text-red" id="tooltip"><a class="self-link" href="#tooltip">Tooltip</a></h3><p>Creates a tooltip above a DOM node which typically shows when the DOM node is being hovered.</p><h4 class="w3-medium w3-text-red" id="signature-4"><a class="self-link" href="#signature-4">Signature</a></h4><pre><code class="language-js">Tooltip({...props}) => <The created tooltip element>
</code></pre><h4 class="w3-medium w3-text-red" id="examples-3"><a class="self-link" href="#examples-3">Examples</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/tooltip?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><pre><code class="language-ts">const tooltip1Show = van.state(false)
const tooltip2Show = van.state(false)
const count = van.state(0)
const tooltip2Text = van.derive(() => `Count: ${count.val}`)
const tooltip3Show = van.state(false)
van.add(document.body,
button({
style: "position: relative;",
onmouseenter: () => tooltip1Show.val = true,
onmouseleave: () => tooltip1Show.val = false,
}, "Normal Tooltip", Tooltip({text: "Hi!", show: tooltip1Show})), " ",
button({
style: "position: relative;",
onmouseenter: () => tooltip2Show.val = true,
onmouseleave: () => tooltip2Show.val = false,
onclick: () => ++count.val
}, "Increment Counter", Tooltip({text: tooltip2Text, show: tooltip2Show})), " ",
button({
style: "position: relative;",
onmouseenter: () => tooltip3Show.val = true,
onmouseleave: () => tooltip3Show.val = false,
}, "Slow Fade-in", Tooltip({text: "Hi from the sloth!", show: tooltip3Show, fadeInSec: 5})),
)
</code></pre><p>Note that the lines:</p><pre><code class="language-ts">{
style: "position: relative;",
onmouseenter: () => ...Show.val = true,
onmouseleave: () => ...Show.val = false,
}
</code></pre><p>are needed for the tooltip element to be shown properly.</p><h4 class="w3-medium w3-text-red" id="property-reference-4"><a class="self-link" href="#property-reference-4">Property Reference</a></h4><ul><li><code class="symbol">text</code>: Type <code class="symbol">string | State<string></code>. Required. The text shown in the tooltip. If a <code class="symbol">State</code> object is specified, you can set the text with <code class="symbol">text.val = ...</code>.</li><li><code class="symbol">show</code>: Type <code class="symbol">State<boolean></code>. Required. The <code class="symbol">State</code> object to control whether to show the tooltip or not.</li><li><code class="symbol">width</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"200px"</code>. Optional. The width of the tooltip.</li><li><code class="symbol">backgroundColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#333D"</code>. Optional. The background color of the tooltip.</li><li><code class="symbol">fontColor</code>: Type <code class="symbol">string</code>. Default: <code class="symbol">"white"</code>. Optional. The font color of the tooltip.</li><li><code class="symbol">fadeInSec</code>: Type <code class="symbol">number</code>. Default <code class="symbol">0.3</code>. Optional. The duration of the fade-in animation.</li><li><code class="symbol">tooltipClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the tooltip. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">tooltipStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the tooltip.</li><li><code class="symbol">triangleClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the triangle in the bottom. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">triangleStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the triangle in the bottom.</li></ul><h3 class="w3-large w3-text-red" id="toggle"><a class="self-link" href="#toggle">Toggle</a></h3><p>Creates a toggle switch that can be turned on and off.</p><h4 class="w3-medium w3-text-red" id="signature-5"><a class="self-link" href="#signature-5">Signature</a></h4><pre><code class="language-js">Toggle({...props}) => <The created toggle switch>
</code></pre><h4 class="w3-medium w3-text-red" id="example-1"><a class="self-link" href="#example-1">Example</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/toggle?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><pre><code class="language-ts">van.add(document.body, Toggle({
on: true,
size: 2,
onColor: "#4CAF50"
}))
</code></pre><h4 class="w3-medium w3-text-red" id="property-reference-5"><a class="self-link" href="#property-reference-5">Property Reference</a></h4><ul><li><code class="symbol">on</code>: Type <code class="symbol">boolean | State<boolean></code>. Default <code class="symbol">false</code>. Optional. A boolean or a boolean-typed <code class="symbol">State</code> object to indicate the status of the toggle. If a <code class="symbol">State</code> object is specified, you can turn on/off the toggle via the specified <code class="symbol">State</code> object with <code class="symbol">on.val = <true|false></code>, and subscribe to the status change of the toggle via <a href="https://vanjs.org/tutorial#api-derive" class="w3-hover-opacity"><code class="symbol">van.derive</code></a>.</li><li><code class="symbol">size</code>: Type <code class="symbol">number</code>. Default <code class="symbol">1</code>. Optional. The size of the toggle. <code class="symbol">1</code> means the height of the toggle is <code class="symbol">1rem</code>.</li><li><code class="symbol">cursor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">pointer</code>. Optional. The <code class="symbol">cursor</code> CSS property of the toggle.</li><li><code class="symbol">ofColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#ccc"</code>. Optional. The color of the toggle when it's off.</li><li><code class="symbol">onColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#2196F3"</code>. Optional. The color of the toggle when it's on.</li><li><code class="symbol">circleColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"white"</code>. Optional. The color of the toggling circle.</li><li><code class="symbol">toggleClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the toggle. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">toggleStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the toggle.</li><li><code class="symbol">sliderClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the slider. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">sliderStyleOverrides</code>. Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the slider.</li><li><code class="symbol">circleClass</code>. Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the toggling circle. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">circleStyleOverrides</code>. Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the toggling circle.</li><li><code class="symbol">circleWhenOnStyleOverrides</code>. Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the toggling circle. Typically this is used to override the <code class="symbol">transform</code> CSS property if the dimensions of the toggle is overridden.</li></ul><h3 class="w3-large w3-text-red" id="optiongroup"><a class="self-link" href="#optiongroup">OptionGroup</a></h3><p>Creates a group of button-shaped options where only one option can be selected. This is functionally similar to a radio group but with a different appearance.</p><h4 class="w3-medium w3-text-red" id="signature-6"><a class="self-link" href="#signature-6">Signature</a></h4><pre><code class="language-js">OptionGroup({...props}, options) => <The created option group>
</code></pre><p>The <code class="symbol">options</code> parameter is a <code class="symbol">string[]</code> for all the options.</p><h4 class="w3-medium w3-text-red" id="example-2"><a class="self-link" href="#example-2">Example</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/option-group?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><pre><code class="language-ts">const selected = van.state("")
const options = ["Water", "Coffee", "Juice"]
van.add(document.body,
p("What would you like to drink?"),
OptionGroup({selected}, options),
p(() => options.includes(selected.val) ?
span(b("You selected:"), " ", selected) : b("You haven't selected anything.")),
)
</code></pre><h4 class="w3-medium w3-text-red" id="property-reference-6"><a class="self-link" href="#property-reference-6">Property Reference</a></h4><ul><li><code class="symbol">selected</code>: Type <code class="symbol">State<string></code>. Required. A <code class="symbol">State</code> object for the currently selected option. You can change the selected option with <code class="symbol">selected.val = <option string></code>, and subscribe to the selection change via <a href="https://vanjs.org/tutorial#api-derive" class="w3-hover-opacity"><code class="symbol">van.derive</code></a>.</li><li><code class="symbol">normalColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#e2eef7"</code>. Optional. The color of the option when it's not selected or hovered.</li><li><code class="symbol">hoverColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#c1d4e9"</code>. Optional. The color of the option when it's hovered.</li><li><code class="symbol">selectedColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#90b6d9"</code>. Optional. The color of the option when it's selected.</li><li><code class="symbol">selectedHoverColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#7fa5c8"</code>. Optional. The color of the option when it's selected and hovered.</li><li><code class="symbol">fontColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"black"</code>. Optional. The font color of the options.</li><li><code class="symbol">transitionSec</code>: Type <code class="symbol">number</code>. Default <code class="symbol">0.3</code>. Optional. The duration of the transition when the options change color.</li><li><code class="symbol">optionGroupClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the entire option group. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">optionGroupStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the entire option group.</li><li><code class="symbol">optionClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the options. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">optionStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the options.</li></ul><h3 class="w3-large w3-text-red" id="banner"><a class="self-link" href="#banner">Banner</a></h3><p>Creates a banner element for the current container.</p><h4 class="w3-medium w3-text-red" id="signature-7"><a class="self-link" href="#signature-7">Signature</a></h4><pre><code class="language-js">Banner({...props}, ...children) => <The created banner element>
</code></pre><h4 class="w3-medium w3-text-red" id="examples-4"><a class="self-link" href="#examples-4">Examples</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/banner?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><pre><code class="language-ts">van.add(document.body,
h2("Sticky Banner"),
div({style: "width: 300px; height: 200px; overflow-y: auto; border: 1px solid #000;"},
Banner({sticky: true}, "👋Hello 🗺️World"),
div({style: "padding: 0 10px"}, Array.from({length: 10}).map((_, i) => p("Line ", i))),
),
h2("Non-sticky Banner"),
div({style: "width: 300px; height: 200px; overflow-y: auto; border: 1px solid #000;"},
Banner({sticky: false}, "👋Hello ", a({href: "https://vanjs.org/"}, "🍦VanJS")),
div({style: "padding: 0 10px"}, Array.from({length: 10}).map((_, i) => p("Line ", i))),
),
)
</code></pre><h4 class="w3-medium w3-text-red" id="property-reference-7"><a class="self-link" href="#property-reference-7">Property Reference</a></h4><ul><li><code class="symbol">backgroundColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">#fff1a8</code>. Optional. The background color of the banner.</li><li><code class="symbol">fontColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">currentcolor</code>. Optional. The font color of the banner.</li><li><code class="symbol">sticky</code>: Type <code class="symbol">boolean</code>. Default <code class="symbol">false</code>. Optional. Whether the banner is sticky on the top.</li><li><code class="symbol">bannerClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the created banner element. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">bannerStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the created banner element.</li></ul><h3 class="w3-large w3-text-red" id="floatingwindow"><a class="self-link" href="#floatingwindow">FloatingWindow</a></h3><p><em>Author: <a href="https://github.com/Duffscs" class="w3-hover-opacity">@Duffscs</a></em></p><p>Creates a movable and resizable floating window.</p><h4 class="w3-medium w3-text-red" id="signature-8"><a class="self-link" href="#signature-8">Signature</a></h4><pre><code class="language-js">FloatingWindow({...props}, ...children) => <The created floating window>
</code></pre><h4 class="w3-medium w3-text-red" id="examples-5"><a class="self-link" href="#examples-5">Examples</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/window?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><p>Window with custom close button:</p><pre><code class="language-ts">const closed = van.state(false)
const width = van.state(300), height = van.state(220)
van.add(document.body, FloatingWindow(
{title: "Example Window 1", closed, width, height, closeCross: null},
div({style: "display: flex; flex-direction: column; justify-content: center;"},
p("Hello, World!"),
button({onclick: () => width.val *= 2}, "Double Width"),
button({onclick: () => height.val *= 2}, "Double Height"),
button({onclick: () => closed.val = true}, "Close Window"),
),
))
</code></pre><p>Window with integrated close button:</p><pre><code class="language-ts">van.add(document.body, FloatingWindow(
{title: "Example Window 2", x: 150, y: 150, headerColor: "lightblue"},
div({style: "display: flex; justify-content: center;"},
p("This is another floating window!"),
),
))
</code></pre><p>Close button with custom appearance:</p><pre><code class="language-ts">van.add(document.body, FloatingWindow(
{
title: "Example Window 3", x: 175, y: 175, closeCross: "❌",
crossHoverStyleOverrides: {"background-color": "white"},
},
div({style: "display: flex; justify-content: center;"},
p("This is a floating window with custom cross button!"),
),
))
</code></pre><p>Window with <code class="symbol">Tabs</code>:</p><pre><code class="language-ts">const closed = van.state(false)
van.add(document.body, FloatingWindow(
{
closed, x: 200, y: 200, width: 500, height: 300,
childrenContainerStyleOverrides: { padding: 0 },
},
div(
span({
class: "vanui-window-cross",
style: "position: absolute; top: 8px; right: 8px;cursor: pointer;",
onclick: () => closed.val = true,
}, "×"),
Tabs(
{
style: "width: 100%;",
tabButtonActiveColor: "white",
tabButtonBorderStyle: "none",
tabButtonRowColor: "lightblue",
tabButtonRowStyleOverrides: {height: "2.5rem"},
tabButtonStyleOverrides: {height: "100%"},
},
{
Home: p(
"Welcome to ", b("VanJS"), " - the smallest reactive UI framework in the world.",
),
"Getting Started": [
p("To install the ", b("VanJS"), " NPM package, run the line below:"),
pre(code("npm install vanjs-core")),
],
About: p(
"The author of ", b("VanJS"), " is ",
a({href: "https://github.com/Tao-VanJS"}, " Tao Xin"), "."
),
},
)
)
))
</code></pre><p>Window without header or integrated close button:</p><pre><code class="language-ts">const closed = van.state(false)
van.add(document.body, FloatingWindow(
{
closed, x: 300, y: 300, width: 500, height: 300,
windowStyleOverrides: {"background-color": "lightgray"},
childrenContainerStyleOverrides: {
display: "flex",
"align-items": "center",
"justify-content": "center",
height: "100%",
}
},
button({onclick: () => closed.val = true}, "Close Window"),
))
</code></pre><p>Window showing z-index:</p><pre><code class="language-ts">const zIndex = van.state(1)
van.add(document.body, FloatingWindow(
{title: ["z-index: ", zIndex], x: 200, y: 200, width: 300, height: 100, zIndex},
))
</code></pre><p>Window with custom stacking:</p><pre><code class="language-ts">const zIndex = van.state(1)
van.add(document.body, FloatingWindow(
{title: "Custom stacking", x: 300, y: 300, customStacking: true, zIndex},
div({style: "display: flex; justify-content: space-between;"},
button({onclick: () => zIndex.val++}, "+"),
p("z-index: ", zIndex),
button({onclick: () => zIndex.val--}, "-"),
),
div({style: "display: flex; justify-content: center;"},
button({onclick: () => zIndex.val = topMostZIndex()}, "Bring to Front"),
),
))
</code></pre><p>Non-movable window:</p><pre><code class="language-ts">van.add(document.body, FloatingWindow(
{title: "Not Movable", disableMove: true},
div({style: "display: flex; justify-content: center;"},
p("This window is not movable!"),
),
))
</code></pre><p>Non-movable window without title:</p><pre><code class="language-ts">const closed = van.state(false)
van.add(document.body, FloatingWindow(
{closed, x: 150, y: 150, disableMove: true},
div(
p("This window is not movable!"),
p({style: "display: flex; justify-content: center;"},
button({onclick: () => closed.val = true}, "Close")
),
),
))
</code></pre><p>Non-resizable window:</p><pre><code class="language-ts">van.add(document.body, FloatingWindow(
{title: "Not Resizable", x: 200, y: 200, disableResize: true},
div(
p({style: "display: flex; justify-content: center;"}, "This window is not resizable!"),
),
))
</code></pre><h4 class="w3-medium w3-text-red" id="default-z-index-stacking"><a class="self-link" href="#default-z-index-stacking">Default <code class="symbol">z-index</code> Stacking</a></h4><p>By default, the <code class="symbol">z-index</code> CSS property of each window comes from the sequence: <code class="symbol">1</code>, <code class="symbol">2</code>, <code class="symbol">3</code>, <code class="symbol">...</code>. Whenever a new window is created or is interacted with (<code class="symbol">onmousedown</code> event is triggered), we assign the <code class="symbol">z-index</code> property of the window to the next number in the sequence. This way, we are making sure that newly created or interacted windows are always brought to the front.</p><p>You can override the default stacking behavior by specifying <code class="symbol">{customStacking: true}</code> in <code class="symbol">props</code>. This way, you can manually control the <code class="symbol">z-index</code> of the window via a <strong>VanJS</strong> state.</p><h4 class="w3-medium w3-text-red" id="property-reference-8"><a class="self-link" href="#property-reference-8">Property Reference</a></h4><ul><li><code class="symbol">title</code>: Type <code class="symbol">ChildDom</code>. Optional. One <code class="symbol">ChildDom</code> or multiple <code class="symbol">ChildDom</code> as an <code class="symbol">Array</code> for the title of the created window. If not specified, the window won't have a title.</li><li><code class="symbol">closed</code>: Type <code class="symbol">State<boolean></code>. Optional. If specified, the created window can be closed via the <code class="symbol">closed</code><code class="symbol">State</code> object with <code class="symbol">closed.val = true</code>. You can also subscribe the closing event of the created window via <a href="https://vanjs.org/tutorial#api-derive" class="w3-hover-opacity"><code class="symbol">van.derive</code></a>.</li><li><code class="symbol">x</code>: Type <code class="symbol">number | State<number></code>. Default <code class="symbol">100</code>. Optional. The x-coordinate of the created window, in pixels.</li><li><code class="symbol">y</code>: Type <code class="symbol">number | State<number></code>. Default <code class="symbol">100</code>. Optional. The y-coordinate of the created window, in pixels.</li><li><code class="symbol">width</code>: Type <code class="symbol">number | State<number></code>. Default <code class="symbol">300</code>. Optional. The width of the created window, in pixels.</li><li><code class="symbol">height</code>: Type <code class="symbol">number | State<number></code>. Default <code class="symbol">200</code>. Optional. The height of the created window, in pixels.</li><li><code class="symbol">closeCross</code>: Type <code class="symbol">ChildDom</code>. Default <code class="symbol">"×"</code>. Optional. One <code class="symbol">ChildDom</code> or multiple <code class="symbol">ChildDom</code> as an <code class="symbol">Array</code> for the close button of the created window. If its value is <code class="symbol">null</code>, there won't be a close button. If <code class="symbol">title</code> property is not specified, this property will be ignored and there won't be a close button.</li><li><code class="symbol">customStacking</code>: type <code class="symbol">boolean</code>. Default <code class="symbol">false</code>. Optional. If <code class="symbol">true</code>, <a href="#default-z-index-stacking" class="w3-hover-opacity">default <code class="symbol">z-index</code> stacking rule</a> won't be triggered. Users are expected to manually set the <code class="symbol">z-index</code> property of the created window via the <code class="symbol">State</code> object for <code class="symbol">z-index</code> property below.</li><li><code class="symbol">zIndex</code>: type <code class="symbol">number | State<number></code>. Optional. If a <code class="symbol">State</code> object is specified, you can use the <code class="symbol">State</code> object to track the change of <code class="symbol">z-index</code> property via <a href="https://vanjs.org/tutorial#api-derive" class="w3-hover-opacity"><code class="symbol">van.derive</code></a>. If <code class="symbol">customTracking</code> is <code class="symbol">true</code>, you can use this property to manually set the <code class="symbol">z-index</code> property of the created window.</li><li><code class="symbol">disableMove</code>: type <code class="symbol">boolean</code>. Default <code class="symbol">false</code>. Optional. If <code class="symbol">true</code>, the created window can't be moved.</li><li><code class="symbol">disableResize</code>: type <code class="symbol">boolean</code>. Default <code class="symbol">false</code>. Optional. If <code class="symbol">true</code>, the created window can't be resized.</li><li><code class="symbol">headerColor</code>: type <code class="symbol">string</code>. Default <code class="symbol">"lightgray"</code>. Optional. The background color of the window header (title bar).</li><li><code class="symbol">windowClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the created window. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">windowStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the created window.</li><li><code class="symbol">headerClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the window header (title bar). You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">headerStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the window header (title bar).</li><li><code class="symbol">childrenContainerClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the container for <code class="symbol">children</code> DOM nodes. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">childrenContainerStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the container of <code class="symbol">children</code> DOM nodes.</li><li><code class="symbol">crossClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the close button. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">crossStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the close button.</li><li><code class="symbol">crossHoverClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the close button when it's hovered over. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">crossStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the close button when it's hovered over.</li></ul><h3 class="w3-large w3-text-red" id="choose"><a class="self-link" href="#choose">choose</a></h3><p>Creates a <a href="#modal" class="w3-hover-opacity"><code class="symbol">Modal</code></a> component that lets the user choose among given options, returns a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="w3-hover-opacity"><code class="symbol">Promise</code></a> that resolves when user makes the choice (resolves to the chosen string), or cancels (resolves to <code class="symbol">null</code>).</p><h4 class="w3-medium w3-text-red" id="signature-9"><a class="self-link" href="#signature-9">Signature</a></h4><pre><code class="language-js">choose({...props}) => Promise<string | null>
</code></pre><h4 class="w3-medium w3-text-red" id="examples-6"><a class="self-link" href="#examples-6">Examples</a></h4><p>Preview with <a href="https://codesandbox.io/p/sandbox/github/vanjs-org/van/tree/main/components/examples/choose?file=%2Fsrc%2Fmain.ts%3A1%2C1" class="w3-hover-opacity">CodeSandbox</a>.</p><p>Example 1:</p><pre><code class="language-ts">const choice = await choose({
label: "Choose a color:",
options: ["Red", "Green", "Blue"],
})
choice && van.add(document.body, div("You chose: ", b(choice)))
</code></pre><p>Example 2:</p><pre><code class="language-ts"> const choice = await choose({
label: "Choose a South American country:",
options: [
"🇦🇷 Argentina", "🇧🇴 Bolivia", "🇧🇷 Brazil", "🇨🇱 Chile", "🇨🇴 Colombia", "🇪🇨 Ecuador",
"🇬🇾 Guyana", "🇵🇾 Paraguay", "🇵🇪 Peru", "🇸🇷 Suriname", "🇺🇾 Uruguay", "🇻🇪 Venezuela",
],
showTextFilter: true,
selectedColor: "blue",
cyclicalNav: true,
customModalProps: {
blurBackground: true,
modalStyleOverrides: {height: "300px"},
},
selectedStyleOverrides: {color: "white"},
})
choice && van.add(document.body, div("You chose: ", b(choice)))
</code></pre><h4 class="w3-medium w3-text-red" id="property-reference-9"><a class="self-link" href="#property-reference-9">Property Reference</a></h4><ul><li><code class="symbol">label</code>: Type <code class="symbol">string</code>. Required. The label you want to show.</li><li><code class="symbol">options</code>: Type <code class="symbol">string[]</code>. Required. The options of the choice.</li><li><code class="symbol">showTextFilter</code>: Type <code class="symbol">boolean</code>. Default <code class="symbol">false</code>. Optional. Whether to show a text filter for the options.</li><li><code class="symbol">selectedColor</code>: Type <code class="symbol">string</code>. Default <code class="symbol">"#f5f5f5"</code>. Optional. The background color of the currently selected option.</li><li><code class="symbol">cyclicalNav</code>: Type <code class="symbol">boolean</code>. Default <code class="symbol">false</code>. Optional. Whether to navigate through the options via arrow keys in a cyclical manner. That is, if <code class="symbol">cyclicalNav</code> is on, when you reach the end of the list, pressing the down arrow key will take you back to the beginning, and vice versa for going up the list with the up arrow key.</li><li><code class="symbol">customModalProps</code>: Type: property bags for the <a href="#modal" class="w3-hover-opacity"><code class="symbol">Modal</code></a> component (except the <code class="symbol">closed</code> field). Default <code class="symbol">{}</code>. Optional. The custom properties for the <code class="symbol">Modal</code> component you want to specify.</li><li><code class="symbol">textFilterClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the text filter. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">textFilterStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the text filter.</li><li><code class="symbol">optionsContainerClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the container of all options. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">optionsContainerStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the container of all options.</li><li><code class="symbol">optionClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of an individual option. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">optionStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for an individual option.</li><li><code class="symbol">selectedClass</code>: Type <code class="symbol">string</code>. Default <code class="symbol">""</code>. Optional. The <code class="symbol">class</code> attribute of the currently selected option. You can specify multiple CSS classes separated by <code class="symbol">" "</code>.</li><li><code class="symbol">selectedStyleOverrides</code>: Type <code class="symbol">Record<string, string | number></code>. Default <code class="symbol">{}</code>. Optional. A <a href="#property-bag-for-style-overrides" class="w3-hover-opacity">property bag</a> for the styles you want to override for the currently selected option.</li></ul><h3 class="w3-large w3-text-red" id="property-bag-for-style-overrides"><a class="self-link" href="#property-bag-for-style-overrides">Property Bag for Style Overrides</a></h3><p>In the API of <strong>VanUI</strong>, you can specify an object as a property bag to override the styles of the created elements. The keys of the property bag are CSS property names, and the values of the property bag are CSS property values. Sample values of the property bag:</p><pre><code class="language-js">{
"z-index": 1000,
"background-color": "rgba(0,0,0,.8)",
}
</code></pre><pre><code class="language-js">{
"border-radius": "0.2rem",
padding: "0.8rem",
"background-color": "yellow",
}
</code></pre></div>
<aside id="toc"><ul><li><a href="#installation" class="w3-hover-opacity">Installation</a><ul><li><a href="#via-npm" class="w3-hover-opacity">Via NPM</a></li><li><a href="#via-a-script-tag" class="w3-hover-opacity">Via a Script Tag</a></li><li><a href="#typescript-support-for-script-tag-integration" class="w3-hover-opacity">TypeScript Support for Script Tag Integration</a></li></ul></li><li><a href="#documentation" class="w3-hover-opacity">Documentation</a><ul><li><a href="#await" class="w3-hover-opacity">Await</a></li><li><a href="#modal" class="w3-hover-opacity">Modal</a></li><li><a href="#tabs" class="w3-hover-opacity">Tabs</a></li><li><a href="#messageboard" class="w3-hover-opacity">MessageBoard</a></li><li><a href="#tooltip" class="w3-hover-opacity">Tooltip</a></li><li><a href="#toggle" class="w3-hover-opacity">Toggle</a></li><li><a href="#optiongroup" class="w3-hover-opacity">OptionGroup</a></li><li><a href="#banner" class="w3-hover-opacity">Banner</a></li><li><a href="#floatingwindow" class="w3-hover-opacity">FloatingWindow</a></li><li><a href="#choose" class="w3-hover-opacity">choose</a></li><li><a href="#property-bag-for-style-overrides" class="w3-hover-opacity">Property Bag for Style Overrides</a></li></ul></li></ul></aside>
</div>
</div>
<script>
// Script to open and close sidebar
const w3_open = () => {
document.getElementById("mySidebar").style.display = "block"
document.getElementById("myOverlay").style.display = "block"
}
const w3_close = () => {
document.getElementById("mySidebar").style.display = "none"
document.getElementById("myOverlay").style.display = "none"
}
const tocDom = document.getElementById("toc")
// Tracks the current toc item
const trackToc = () => {
const allHeadings = [...document.querySelectorAll("h2,h3")]
const currentHeadingIndex = allHeadings.findIndex(h => h.getBoundingClientRect().top >= 0)
let currentHeading
if (currentHeadingIndex < 0) currentHeading = allHeadings[allHeadings.length - 1]; else {
currentHeading = allHeadings[currentHeadingIndex]
if (currentHeadingIndex > 0 && currentHeading.getBoundingClientRect().top > innerHeight)
currentHeading = allHeadings[currentHeadingIndex - 1]
}
for (const e of document.querySelectorAll("#toc li a"))
if (e.href.split("#")[1] === currentHeading?.id) {
e.classList.add("current-heading")
const {top: tocTop, bottom: tocBottom} = tocDom.getBoundingClientRect()
const {top: eTop, bottom: eBottom} = e.getBoundingClientRect()
if (eBottom > tocBottom) tocDom.scrollTop += eBottom - tocBottom
else if (eTop < tocTop) tocDom.scrollTop -= tocTop - eTop
} else
e.classList.remove("current-heading")
}
trackToc()
document.addEventListener("scroll", trackToc)
addEventListener("resize", trackToc)
const copy = e => {
const file = e.previousElementSibling.innerText
const importLine = file.includes("nomodule") ?
`<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/vanjs-org/van/public/${file}"><\/script>` :
`import van from "https://cdn.jsdelivr.net/gh/vanjs-org/van/public/${file}"`
navigator.clipboard.writeText(importLine)
.then(() => e.querySelector(".tooltip").innerText = "Copied")
.catch(() => e.querySelector(".tooltip").innerText = "Copy failed")
}
const resetTooltip = e => e.querySelector(".tooltip").innerText = "Copy import line"
</script>
<script src="https://guru-widget.pages.dev/guru_widget.latest.min.js" data-text="Ask AI" data-link="https://gurubase.io/g/vanjs" data-bg-color="rgba(244, 67, 54, 0.3)" data-icon-url="/ask_ai.svg" data-font-color="#ffffff" data-margins="{"bottom": "1rem", "left": "1430px", "right": "unset"}">
</script>
<!-- Place this tag in your head or just before your close body tag. -->
<script async defer src="https://buttons.github.io/buttons.js"></script>
<link rel="prefetch" href="/code/prism-v1.js" as="script"><link rel="prefetch" href="https://www.gstatic.com/charts/loader.js" as="script"><link rel="prefetch" href="/code/diff.min.js" as="script"><link rel="prefetch" href="/code/van-1.5.3.nomodule.min.js" as="script"><link rel="prefetch" href="/code/van-x-0.6.2.nomodule.min.js" as="script"></body></html>