DOCSEARCHbyAlgolia
Submit Docs

VanJS Documentation

repository·main·Indexed 26 days ago

https://github.com/vanjs-org/van

An ultra-lightweight (1.0kB gzipped), zero-dependency reactive UI framework based on vanilla JavaScript and the DOM. It avoids virtual DOM and JSX by default, though it provides optional addons including vanjs-jsx for JSX support, vanjs-element for Web Components, vanjs-prerender for static HTML generation, and van_dml for auto-appending elements and dynamic CSS. The ecosystem also includes VanUI for pre-built components like Modal and Await.

Tokens
13.5K
Snippets
36
Records
83
Agent score
88%

What's inside VanJS

  1. Use VanX to extend VanJS

    main
    VanX is the official 1.2kB extension for VanJS. It provides a collection of utility functions designed to improve developer ergonomics and bring the VanJS developer experience closer to other popular UI frameworks.

  2. Configure TypeScript support for Script Tag integration

    main

    If you are using VanUI via a <script> tag but want TypeScript type definitions, download the van-ui.d.ts file and declare the components at the top of your .ts file to enable autocompletion and type checking.

    import type { Modal as ModalType } from "./van-ui.d.ts"

declare const Modal: typeof ModalType

  3. Update index.html for JSX entry point

    main

    When switching to a .tsx entry point, ensure your index.html script tag points to the correct file path (e.g., /src/main.tsx).

    <body id="app">
  <div id="app"></div>
  <!-- change script src -->
  <script type="module" src="/src/main.tsx"></script>
</body>

  5. Create Web Components with vanjs-element

    main

    Use vanjs-element to wrap VanJS components into standard Web Components. This allows you to define custom HTML tags that encapsulate VanJS logic, styles, and slots.

    Key benefits include:

    • Automatic hydration of VanJS inside your HTML.
    • Reusable components with minimal boilerplate.
    • Isolated styles and support for <slot> elements via the Web Components API.
    • Extremely lightweight (~300b min+gzip).
    import van from "vanjs-core";
import { define } from "vanjs-element";

const { button, div, slot } = van.tags;

define("custom-counter", () => {
  const counter = van.state(0);
  return div(
    slot(),
    counter,
    button({ onclick: () => ++counter.val }, "+"),
    button({ onclick: () => --counter.val }, "-")
  );
});

  7. Use TypeScript with VanJS

    main
    VanJS provides first-class TypeScript support via .d.ts files. To enable type-checking and IntelliSense, download the appropriate .d.ts file corresponding to your version from the official VanJS start page.

  8. Mount a JSX component in main.tsx

    main

    To render your JSX component, rename your entry point from main.ts to main.tsx, import van from vanjs-core, and use van.add() to mount the component to a DOM element.

    import van from "vanjs-core";
import Hello from "./Hello";

van.add(document.getElementById("app")!, <Hello name={"your name"} />);

  9. Use auto-append with begin() and end()

    main

    The begin(ID) function selects a base element (either a DOM element or an HTML ID string). All elements created after begin() are automatically appended as children to this base. Use end() to stop appending and return to the previous base. begin() and end() can be nested.

    begin(ID) is transparent and returns the DOM reference of the first child, allowing you to chain property assignments.

  11. Install van_dml

    main

    To use van_dml, include the van_dml.js script immediately after the VanJS script. You can load them locally or via a CDN.

    <!-- Local installation -->
<script src="van-latest.nomodule-min.js"></script>
<script src="van_dml.js"></script>

<!-- CDN installation -->
<script src="https://cdn.jsdelivr.net/gh/vanjs-org/van/public/van-latest.nomodule.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/vanjs-org/van/addons/van_dml/src/van_dml.js"></script>

  12. Install and setup van_dml.js

    main

    To use the van_dml addon, include the core VanJS library followed by the van_dml.js script. The addon extends the van object with new functions like begin, end, base, sp, and css.

    <script src="https://cdn.jsdelivr.net/gh/vanjs-org/van/public/van-latest.nomodule.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/vanjs-org/van/addons/van_dml/src/van_dml.js"></script>

<script>
    const { h1, h2, div, p, button } = van.tags;
    const { begin, end, base, sp, css } = van; // new functions of van_dml
</script>