@tooark/vue

Vue 3 wrappers for the Tooark Web Components: typed props, native event names delivering the CustomEvent (or its detail), object props serialized for you.

🌍 Languages: English (this file) · Português

📑 Contents

• Overview
• Installation
• Configuration
• Components
• Usage examples
• Dependencies
• Contributing
• Help & Security
• Support
• License

📖 Overview

The @tooark/vue package provides:

• one defineComponent per element (ArkButton, ArkInput, ArkDialog, …) with typed props and inheritAttrs: false, so extra attributes and native listeners go straight to the element;
• custom events re-emitted with their native names (@ark-close, @ark-select, @change on ArkSelect, …) delivering the CustomEvent or, on the calendar, datepicker, clock, carousel and scheduler, its detail;
• object props (events, rows, options, and localeJson on ArkCalendar/ArkDatepicker) serialized or assigned as properties for you (on the other wrappers localeJson is a JSON string);
• the elements register themselves on first render, browser only (Nuxt-safe);
• toast re-exported from @tooark/core.

🔧 Installation

pnpm add @tooark/vue @tooark/web-components

@tooark/vue already depends on @tooark/web-components, @tooark/core and @tooark/tokens, but pnpm does not expose transitive dependencies to your app, and the stylesheet import below comes from @tooark/web-components: install it directly. toast is re-exported by @tooark/vue.

Peer dependency: vue ≥ 3.

⚙️ Configuration

Import the stylesheet once in main.ts. If you also use raw ark-* tags (side packages), tell the compiler they are custom elements:

// main.ts
import "@tooark/web-components/styles.css";

// vite.config.ts
import vue from "@vitejs/plugin-vue";

export default {
  plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("ark-") } } })],
};

📦 Components

One wrapper per element, named after it: ark-button → ArkButton, ark-kv-editor → ArkKvEditor, ark-command-palette → ArkCommandPalette + ArkCommandItem.

• Props: the element's attributes in camelCase (iconOnly, stepMinutes, localeJson), testid for the E2E hooks, plus its JS properties where they matter (events, rows, options, sizes, and valueField on ArkKvEditor).
• Events: the custom events with their native names (@ark-close on ArkDialog/ArkDrawer, @ark-select on ArkMenu/ArkCommandPalette, @change on ArkSelect/ArkKvEditor with $event.detail, …); @ark-change on ArkCalendar/ArkDatepicker/ArkClock, @ark-slide-change on ArkCarousel and @ark-event-click/@ark-slot-click/@ark-view-change/@ark-range-change on ArkScheduler deliver the detail itself; native events bubble from the inner control (@input on ArkInput: read $event.target.value).
• State: attributes like open are the source of truth (:open="bool" + @ark-close).

Full attribute reference, theming guide and E2E hooks: https://github.com/Tooark/web-components#readme · live examples with interaction tests: Storybook.

📝 Usage examples

A form with a confirmation dialog and a toast

<script setup lang="ts">
import { ArkButton, ArkDialog, ArkInput, ArkSelect, ArkToaster, toast } from "@tooark/vue";
import { ref } from "vue";

const roles = [
  { value: "dev", label: "Developer" },
  { value: "ops", label: "Operations" },
];
const name = ref("");
const role = ref("dev");
const confirming = ref(false);

function publish() {
  confirming.value = false;
  toast.success("Profile published", { description: `Welcome, ${name.value}.` });
}
</script>

<template>
  <form @submit.prevent="confirming = true">
    <ArkInput label="Name" :value="name" required @input="name = ($event.target as HTMLInputElement).value" />
    <ArkSelect label="Role" :options="roles" :value="role" @change="role = $event.detail.value" />
    <ArkButton type="submit" intent="primary">Save</ArkButton>

    <ArkDialog label="Publish changes?" :open="confirming" @ark-close="confirming = false">
      <p>Your profile will be visible to the whole team.</p>
      <div slot="footer">
        <ArkButton variant="ghost" @click="confirming = false">Cancel</ArkButton>
        <ArkButton intent="primary" @click="publish">Publish</ArkButton>
      </div>
    </ArkDialog>

    <ArkToaster position="bottom-right" />
  </form>
</template>

A raw element from a side package

<script setup lang="ts">
import { registerTooarkCode } from "@tooark/code";
import { onMounted, ref } from "vue";

const editor = ref<HTMLElement & { value: string }>();
onMounted(() => {
  registerTooarkCode();
  editor.value!.value = JSON.stringify({ hello: "world" }, null, 2);
});

function save(value: string) {
  localStorage.setItem("config", value);
}
</script>

<template>
  <ark-code-editor ref="editor" language="json" @change="save($event.detail.value)" />
</template>

📋 Dependencies

Installed automatically unless marked as peer; peer dependencies are yours to install (the ranges are what the package declares).

| Package | Version | Description | | -------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------- | | @tooark/core | ^1.4.0 | Types, i18n, toast/announce services, motion and overlay helpers | | @tooark/web-components | ^1.4.0 | The ark-* Custom Elements and their stylesheet | | vue | >=3 (peer) | Vue 3 |

🪪 Contributing

Contributions are welcome! Open issues and pull requests in the Tooark/web-components repository; CONTRIBUTING.md covers the workflow, the commit convention and the checklist. @tooark/vue is released in lockstep with every other @tooark/* package.

🆘 Help & Security

• ❓ Questions, bugs, feature ideas — see SUPPORT.md for the right channel
• 🔒 Security vulnerabilities — do not open a public issue; follow SECURITY.md

💖 Support

If this project helps your workflow, consider supporting its development:

• 💙 GitHub Sponsors
• ☕ Ko-fi

Every contribution helps keep the project maintained and improving. Thank you! 🙏

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.