Skip to content
CONSTRUCTING

Rive Canvas (Lazy Teleport) Alpha

Word count
1644 words
Reading time
11 minutes

🛑 This package is still in the Alpha test stage.

This package is still in the Alpha test stage and is not recommended for use in production. The API may change in the future, and there may be errors in the current version. Please use it with caution.

Introduce

Rive Canvas is a very special component. Unlike regular components, regular components refer to components in other Vue components in the form of direct <ComponentName />, while Rive Canvas (Lazy Teleport) introduces Rive animation into the page by adding specific tags to HTML with the <NuLazyTeleportRiveCanvas /> component referenced elsewhere.

When will such components need to be used?

  1. For VitePress or other static generators, not every document and frontmatter parameter supports rendering as a Vue component. If the Vue component is inserted directly in v-html, it cannot be rendered. You need to use a component such as Rive Canvas (Lazy Teleport) to introduce Rive animation through a placeholder HTML tag until the page is loaded.
  2. If you also use static generators like Astro and Rspress, you may find that inserting Vue components in Markdown is not supported. At this time, you can also use Rive Canvas (Lazy Teleport) Such a component.

Example

Installation

Install @nolebase/ui-rive-canvas to your project dependencies by running the following command:

shell
ni @nolebase/ui-rive-canvas
shell
pnpm add @nolebase/ui-rive-canvas
shell
npm install @nolebase/ui-rive-canvas
shell
yarn add @nolebase/ui-rive-canvas

Usage

Register as a global component

First, you need to import the NuLazyTeleportRiveCanvas component in the Vue component and then register it as a global component:

ts
import { 
NuLazyTeleportRiveCanvas
} from '@nolebase/ui-rive-canvas';
app
.
component
('NuLazyTeleportRiveCanvas',
NuLazyTeleportRiveCanvas
);

Configure Vite

Since <NuLazyTeleportRiveCanvas /> depends on @rive-app/canvas. If you also use Vite as your bundler and development environment server, you need to add the following configuration to your vite.config.ts file like this:

ts
import { 
defineConfig
} from 'vite'
export default
defineConfig
(() => {
return {
optimizeDeps
: {
include
: [
// 添加这一行到你的 vite.config.ts 的 optimizeDeps.include 数组中 '@nolebase/ui-rive-canvas > @rive-app/canvas', ], }, } })

For more information about why configure this, please refer to the Dep Optimization Options | Vite documentation.

Also, for Rive, the file format .riv used by Rive is not the default file format supported by Vite. The file format used by Rive .riv is also not the default file format supported by Vite, so you may need to add the following configuration:

ts
// .vitepress/config.ts
import { 
defineConfig
} from 'vite'
export default
defineConfig
(() => {
return {
assetsInclude
: [
'**/*.riv', ], } })

For more information about why configure this, please refer to the Shared Options | Vite documentation.

Import and use in entry file

Then add the <NuLazyTeleportRiveCanvas /> component in the entry file (App.vue):

vue
<script setup lang="ts">
import { 
NuLazyTeleportRiveCanvas
} from '@nolebase/ui-rive-canvas'
</script> <template> <
NuLazyTeleportRiveCanvas
/>
</template>

Or add <NuLazyTeleportRiveCanvas /> component into layout-top slot you can specify in theme/index.ts of VitePress:

ts
// .vitepress/theme/index.ts
import { 
h
} from 'vue'
import
DefaultTheme
from 'vitepress/theme'
import {
NuLazyTeleportRiveCanvas
} from '@nolebase/ui-rive-canvas'
export default {
extends
:
DefaultTheme
,
Layout
() {
return
h
(
DefaultTheme
.
Layout
, null, {
'layout-top': () => [
h
(
NuLazyTeleportRiveCanvas
)
] }) } }

Adding placeholder elements for Rive Canvas in HTML will render the placeholder tag of Canvas

Next, wherever raw HTML rendering (v-html) is supported, just add the following attribute to the tag that is expected to be rendered as a Canvas:

  • class="rive-canvas"
  • data-rive-canvas="true"
  • data-rive-src="<rive file path>"

Attention

Since Rive Canvas (Lazy Teleport) is introduced via HTML tags, any .riv Rive files referenced by Rive Canvas (Lazy Teleport) will not be automatically processed by Vite, so you will need to manually place the Rive file in a location such as public folder. automatically processed by Vite, so you'll need to manually place the Rive file in a folder such as public and fill in the data-rive-src attribute with the correct path.

For example:

html
<span
  class="rive-canvas"
  data-rive-canvas="true"
  data-rive-src="/icons/star-emoji-animated.riv"
></span>

Customization

Adjust the size

By default, Rive Canvas creates a 500 x 500 canvas. You can customize the size of the canvas by adding the two attributes:

  • data-rive-canvas-props-canvas-width
  • data-rive-canvas-props-canvas-width
Low-res with 25 x 25
High-res with 1000 x 1000
html
<span
  class="rive-canvas"
  data-rive-canvas="true"
  data-rive-src="/icons/star-emoji-animated.riv"
  data-rive-canvas-props-canvas-width="25"
  data-rive-canvas-props-canvas-height="25"
>
</span>

References

Props

data-rive-canvas-props-canvas-width

The width of the <canvas> itself.

Description: It can be understood as the resolution, which is independent of the CSS width. The size of this value will affect the resolution of the animation rendered on the canvas, but at the same time, if the set value is too large, it will cause the rendering performance of the animation to decrease.

Default value: 500

data-rive-canvas-props-canvas-height

The height of the <canvas> itself.

Description: It can be understood as the resolution, which is independent of the CSS height. The size of this value will affect the resolution of the animation rendered on the canvas, but at the same time, if the set value is too large, it will cause the rendering performance of the animation to decrease.

Default value: 500

data-rive-canvas-props-width

The CSS min-width of the <canvas>.

Description: This value will affect the CSS width of the <canvas>, but will not affect the resolution of the animation rendered on the canvas. It can be adjusted according to the requirements of different locations. Just treat it as a normal CSS min-width property.

Default value: 16px

data-rive-canvas-props-height

The CSS min-height of the <canvas>.

Description: This value will affect the CSS height of the <canvas>, but will not affect the resolution of the animation rendered on the canvas. It can be adjusted according to the requirements of different locations. Just treat it as a normal CSS min-height property.

Default value: 16px

data-rive-canvas-props-padding-top

The CSS padding-top of the <canvas>.

Description: Generally speaking, the rendering of Rive and Lottie animations should be full-screen, which means that in most cases, the animation will occupy the entire canvas. However, if you need to add some extra space around the animation, you can adjust it with this attribute.

Default value: 4px

data-rive-canvas-props-padding-bottom

The CSS padding-bottom of the <canvas>.

Description: Generally speaking, the rendering of Rive and Lottie animations should be full-screen, which means that in most cases, the animation will occupy the entire canvas. However, if you need to add some extra space around the animation, you can adjust it with this attribute.

Default value: 4px

data-rive-canvas-props-padding-left

The CSS padding-left of the <canvas>.

Description: Generally speaking, the rendering of Rive and Lottie animations should be full-screen, which means that in most cases, the animation will occupy the entire canvas. However, if you need to add some extra space around the animation, you can adjust it with this attribute.

Default value: 4px

data-rive-canvas-props-padding-right

The CSS padding-right of the <canvas>.

Description: Generally speaking, the rendering of Rive and Lottie animations should be full-screen, which means that in most cases, the animation will occupy the entire canvas. However, if you need to add some extra space around the animation, you can adjust it with this attribute.

Default value: 4px

Annotation

The cute animated emojis are Animated Emoji authored by wonderful Telegram team.

These Emoji can be directly downloaded by dragging the Emoji from Telegram into the browser. However, the downloaded file is a file with the extension .tgs, but fortunately, the community has powerful contributors who have made a TGS to Lottie conversion tool Lottie/TGS Editor, which can be imported by importing the .tgs file, then export it as a Lottie .json file, and then convert the Lottie .json file to a Rive .riv file through the Rive online editor.

Fun fact

In fact, the .tgs file is a .zip compression format derived from the AE plugin bodymovin over Telegram's fork based on the original one. There's actually a Lottie JSON file inside, which is why converting through Lottie/TGS Editor is possible.

If you want to know which Animated Emoji are available, you can check them out through Animated Telemoji - Telegram or Animated Emoji Pack.

Of course, everyone loves cute Emoji, and Microsoft's Fluent Emoji is also a very interesting Emoji. Someone has also made an animated version of the Emoji for them. You can check them out through the Animated Fluent Emojis - Microsoft list.

Contributors

Changelog