Three Vue3Three Vue3
Guide
Demo
AI Agents
  • English
  • 简体中文
GitHub
Guide
Demo
AI Agents
  • English
  • 简体中文
GitHub
    • Getting Started
    • Scene
    • Parameter Bus
    • SkyBox
    • Model Loader

      • Component Loader
      • Function Loader
    • Popup
    • Callout
      • Default Usage
      • Constructor
      • Options
      • Methods
      • Class usage
    • Movable Element
    • Animation
    • Model Rotator
    • Picker
    • Fit Camera
    • Mesh

      • Wave Circle Mesh
      • Flow Line Mesh
    • Effect

      • Nature

        • Rain
        • Snow
        • Water
        • Water Pool
        • Sandy Beach
      • Sky & Atmosphere

        • Sky Dome
        • HeightFog
        • Nebula Galaxy
      • Light

        • Bloom
        • Sweep Light
        • Light Gradient
        • Light Pillar
        • Radar Sweep
        • Signal Wave
        • Force Shield
      • Particles & Sprites

        • Fireworks
        • Text Fireworks
        • Glow Sprite
    • GIS

      • Geographic Reference
      • GeoObject
      • GeoJsonLayer
      • Tile Layer

type

Class

Callout draws a leader line from a 3D anchor point to a label position, with an optional anchor dot and a DOM label at the end. The line can be straight or broken into two segments with a corner, the label can be anchored to a fixed corner or slide along its bottom edge, and the label position can be animated with moveTo. The label animation and the auto-anchor refresh run on the callout's own animation loop, so no per-frame code is needed.

The label is a CSS2DObject, so it is drawn by the CSS2DRenderer that <tv-scene> already renders. content accepts a plain string, which is written as text into a wrapper element, or any HTMLElement you want to mount. The container element is appended to document.body and gets the id callout-<uuid>.

Default Usage

Click me to view the codes
<template>
  <tv-scene class="scene" bg-color="rgb(40, 42, 54)" @created="created"></tv-scene>
</template>

<script lang="ts" setup>
import { onBeforeUnmount } from 'vue'
import * as THREE from 'three'
import { Callout } from 'three-vue3'

let callout: Callout | undefined

const created = (scene, { camera }) => {
  camera.position.set(0, 0, 5)
  camera.lookAt(0, 0, 0)

  // A box at the origin that the annotation points to.
  const box = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshNormalMaterial())
  scene.add(box)

  const label = document.createElement('div')
  label.textContent = 'This is a box!'
  label.style.padding = '8px 14px'
  label.style.background = 'linear-gradient(180deg, #ff8a2b 0%, #e66400 100%)'
  label.style.borderRadius = '4px'
  label.style.color = '#1a0f00'
  label.style.fontSize = '16px'
  label.style.fontWeight = '600'
  label.style.pointerEvents = 'auto'
  label.style.whiteSpace = 'nowrap'

  // Start on the box corner, end out to the right. `autoAnchor` keeps the
  // connection point facing the camera and `attach()` starts the loop.
  callout = new Callout([0.5, 0.5, 0.5], [1.5, 1.0, 0.5], label, {
    color: '#ffffff',
    lineWidth: 2,
    lineShape: 'broken',
    bendAxis: 'x',
    bendRatio: 2 / 3,
    autoAnchor: true,
    dashed: false,
    showDot: true,
    dotColor: '#ffffff',
    dotRadius: 0.06
  })
  scene.add(callout.scene)
  callout.attach(camera)
}

onBeforeUnmount(() => {
  callout?.dispose()
  callout = undefined
})
</script>

<style>
.scene {
  margin-top: 10px;
  margin-bottom: 16px;
  width: 100%;
  height: 360px;
}
</style>

Constructor

new Callout(start: Position, end: Position, content: string | HTMLElement, options?: CalloutOptions)
NameTypeDescription
startPositionAnchor point of the line in world space.
endPositionLabel position in world space; the label is centered here unless labelAnchor or autoAnchor says otherwise.
contentstring | HTMLElementLabel content. A string is written as text into a wrapper element.
optionsCalloutOptionsOptional configuration, see below.

Options

NameTypeDefaultDescription
colornumber | string0xffffffoptional Line color.
lineWidthnumber1optional Line width (WebGL2 only).
lineShapeLineShape'broken'optional Line shape: 'straight' for a direct line, 'broken' for an L-shape with a corner.
bendAxisBendAxis'auto'optional Primary axis for the label-parallel segment of a broken line; 'auto' uses the largest delta.
bendRationumber0.45optional Ratio (0–1) along bendAxis from the label towards the anchor where the corner is placed.
labelAnchorLabelAnchor'bottom-left'optional Which corner/point of the label sits at end; ignored when autoAnchor is true.
autoAnchorbooleanfalseoptional Slide the connection point along the label's bottom edge based on the screen-space direction from end to start.
dashedbooleanfalseoptional Use a dashed line.
dashSizenumber0.1optional Dash size for a dashed line.
gapSizenumber0.05optional Gap size for a dashed line.
showDotbooleantrueoptional Show an anchor dot at the start point.
dotColornumber | stringsame as coloroptional Anchor dot color.
dotRadiusnumber0.05optional Anchor dot radius.
showLabelbooleantrueoptional Show the label at the end point.

LineShape is 'straight' | 'broken', BendAxis is 'auto' | 'x' | 'y' | 'z', and LabelAnchor is 'center' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'.

Methods

NameDescription
attach(camera)Store the camera used by autoAnchor and start the callout's own refresh loop.
detach()Stop the loop and stop tracking the camera.
moveTo(end, duration)Animate the label to a new position; duration is in milliseconds.
setStart(start)Instantly move the anchor point.
setEnd(end)Instantly move the label point.
setLineShape(shape, opts?)Switch between 'straight' and 'broken', optionally with a new bendAxis / bendRatio.
dispose()Dispose the line and dot, remove the label DOM element and detach the camera.

Class usage

import * as THREE from 'three'
import { Callout } from 'three-vue3'

const callout = new Callout(
  [0.5, 0.5, 0],
  [2, 1.5, 0],
  'A sphere in the scene',
  { color: '#8ab4ff', dashed: true }
)
scene.add(callout.scene)

// Only needed when using autoAnchor, so the connection point can follow the camera:
callout.attach(camera)

// Animate the label to a new position over 800 ms:
callout.moveTo([1.2, 2, 0], 800)

// Mount a custom element instead of a string:
const label = document.createElement('strong')
label.textContent = 'Custom'
label.style.color = '#ffd166'
const custom = new Callout([0, 0, 0], [1, 1, 0], label)

// On teardown:
callout.dispose()
custom.dispose()
Edit this page on GitHub
Last Updated:
Contributors: Shing Rui
Prev
Popup
Next
Movable Element