Vue

To make working with Cosmos web components more convenient and practical, we provide a Vue 3 wrapper library in the @cosmos/web-vue package.

Use web components as first-class Vue components

The Vue wrapper hides all the quirks when working with web components and makes integrating Cosmos feel as native as working with Vue components.

Typescript support for properties, events, and methods

We provide type definitions for properties and methods as part of the Vue wrapper.

Auto-definition of required web components

The wrapping component takes care of registering and defining the required web components in the background the moment you are using the Vue component.

⚠️ Deprecation

With release v9.7.0 the Vue wrapper is provided as standalone package. For projects upgrading from a previous version, the dependencies and imports of the core package @cosmos/web have to be replaced with @cosmos/web-vue (deprecation roadmap)

"dependencies": {
  // "@cosmos/web": "9.6.0",
  "@cosmos/web-vue": "9.7.0"
}

Usage

<script lang="ts">
  import { defineComponent } from 'vue';
  import { CosmosButton } from '@cosmos/web-vue';

  export default defineComponent({
    components: { CosmosButton }
  })
</script>

<template>
  <CosmosButton
    kind='tertiary'
    size='small'
    >
      Cosmos Button
  </CosmosButton>
</template>

Custom Events

Subscribe to events emitted by Cosmos web components.

<script lang="ts">
  import { defineComponent } from 'vue';
  import { CosmosStoryCard } from '@cosmos/web-vue';
  
  export default defineComponent({
    components: { CosmosStoryCard },
    methods: {
      handleResize: (event) => {
        console.log(event.detail);
      }}
    });
</script>

<template>
  <CosmosStoryCard
    observeMediaResize
    @mediaresize="handleResize">
  </CosmosStoryCard>
</template>

Typescript

All Cosmos Vue web components are strongly typed to ensure type-safe usage in Typescript environments.

<script lang="ts">
  import { defineComponent } from "vue";
  import { CosmosButton } from "@cosmos/web-vue";
  
  import type { CosmosButtonProps } from "@cosmos/web-vue";

  const buttonProps: CosmosButtonProps = {
    kind: "tertiary",
    size: "small",
    shape: "rectangle",
    appearance: "dark",
  };
  
  export default defineComponent({
    components: { CosmosButton },
    setup() {
      const buttonProps: CosmosButtonProps = {
        kind: "tertiary",
        size: "small",
        shape: "rectangle",
        appearance: "dark",
      };

      return { buttonProps };
    }
  });
</script>

<template>
  <CosmosButton v-bind="buttonProps">Cosmos Button</CosmosButton>
</template>

Reference the Custom Element

Sometimes a reference to the underlying rendered custom element is required in order to call public methods or utilize the Javascript DOM API.

<script lang="ts">
  import { defineComponent } from "vue";
  import { CosmosButton } from "@cosmos/web-vue";
  import type { CosmosButtonElement } from "@cosmos/web-vue";
  
  
  export default defineComponent({
    components: { CosmosButton },
    mounted(){
      const button : CosmosButtonElement = this.$refs.button.$el;
      console.log(button);
    }
  });
</script>

<template>
  <CosmosButton ref="button">Cosmos Button</CosmosButton>
</template>