vue-mermaid-string

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:

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