Skip to content

A Vue.js component that turns a Mermaid string into a diagram.

License

Notifications You must be signed in to change notification settings

dword-design/vue-mermaid-string

Repository files navigation

vue-mermaid-string

npm version Linux macOS Windows compatible Build status Coverage status Dependency status Renovate enabled
Open in Gitpod Buy Me a Coffee PayPal Patreon

A Vue.js component that turns a Mermaid string into a diagram.

In contrast to vue-mermaid, which works by passing structured data to it, this component uses the diagram string directly. The advantage is that it always supports the latest language standard and is easier to use if you have an existing diagram. Depends on your use case which fits better.

Install via a package manager

# npm
$ npm install vue-mermaid-string

# Yarn
$ yarn add vue-mermaid-string

Add to local components:

<script>
import VueMermaidString from 'vue-mermaid-string'

export default {
  components: {
    VueMermaidString,
  },
}
</script>

Or register as a global component:

import VueMermaidString from 'vue-mermaid-string'

app.component('VueMermaidString', VueMermaidString)

Or register as a plugin:

import VueMermaidString from 'vue-mermaid-string'

app.use(VueMermaidString)

Install via CDN

<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
<script src="https://unpkg.com/vue-mermaid-string"></script>

Version compatibility

vue-mermaid-string Vue.js
>= v4 v3
<= v3 v2

Usage

Usage is simple, you pass a Mermaid string to the component and you get a visual diagram. For ease of use, we will use the endent package to declare multiline strings. Of course you can also write them using \n.

<template>
  <vue-mermaid-string :value="diagram" />
</template>
<script>
import endent from 'endent'

export default {
  computed: {
    // equals graph TD\n  A --> B
    diagram: () => endent`
      graph TD
        A --> B
    `,
  },
}
</script>

Mermaid options

It is possible to customize the diagram by passing options to the component. The options are internally passed to mermaid.initialize. See the default config for a list of available options.

<template>
  <vue-mermaid-string :value="diagram" :options="{ maxTextSize: 10000 }" />
</template>

Click events

You can register click events by declaring them in the diagram string. To react to a click event, you need to declare it in the diagram via a click <nodeId> declaration. See the Mermaid docs for details.

When registering a callback, you do not need to specify the callback name, the component will magically inject it into the diagram by itself. Implement the node-click event handler to react to click events:

<template>
  <vue-mermaid-string :value="diagram" @node-click="nodeClick" />
</template>
<script>
import endent from 'endent'

export default {
  computed: {
    diagram: () => endent`
      graph TD
        A --> B
        click A
        click B
    `,
  },
  methods: {
    nodeClick: nodeId => console.log(nodeId),
  },
}
</script>

You can also still implement node links. In this case, the handler won't be called but instead the node will be an <a> tag that opens the link on click:

<template>
  <vue-mermaid-string :value="diagram" />
</template>
<script>
import endent from 'endent'

export default {
  computed: {
    diagram: () => endent`
      graph TD
        A --> B
        click B href "https://github.com"
    `,
  },
}
</script>

Error handling

Mermaid has its own default error handling behavior, outputting a little graphical error message if a parsing error occurs. If you want to have custom error handling, you can react to the @parse-error event. Here is a simple example that outputs the error message as a plain string:

<template>
  <div v-if="error">{{ error }}</div>
  <self v-else value="foo" @parse-error="error = $event" />
</template>
<script>
export default {
  data: () => ({
    error: undefined,
  }),
}
</script>

Contribute

Are you missing something or want to contribute? Feel free to file an issue or a pull request! ⚙️

Support

Hey, I am Sebastian Landwehr, a freelance web developer, and I love developing web apps and open source packages. If you want to support me so that I can keep packages up to date and build more helpful tools, you can donate here:

Buy Me a Coffee  If you want to send me a one time donation. The coffee is pretty good 😊.
PayPal  Also for one time donations if you like PayPal.
Patreon  Here you can support me regularly, which is great so I can steadily work on projects.

Thanks a lot for your support! ❤️

See also

  • nuxt-mermaid-string: Embed a Mermaid diagram in a Nuxt.js app by providing its diagram string.

License

MIT License © Sebastian Landwehr