SVG ^3.3.0

A wrapper around the three SVGLoader, this component allows you to easily load and display SVG elements in your TresJS scene.

Usage

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { OrbitControls, SVG } from '@tresjs/cientos'

const svgURL = 'https://raw.githubusercontent.com/'
  + 'Tresjs/assets/main/svgs/cientos_heart.svg'
</script>

<template>
  <TresCanvas clear-color="#333">
    <OrbitControls />
    <Suspense>
      <SVG 
        :src="svgURL"
        :position="[-0.4, 1, 0]"
        :scale="0.01"
      />
    </Suspense>
    <TresGridHelper />
  </TresCanvas>
</template>

Props

Prop	Type	Description	Default
src	string	Either a path to an SVG or an SVG string
skipStrokes	boolean	If true, the SVG strokes will not be rendered.	false
skipFills	boolean	If true, the SVG fills will not be rendered.	false
strokeMaterial	MeshBasicMaterialParameters	Props to assign to the stroke materials of the resulting meshes.	undefined
fillMaterial	MeshBasicMaterialParameters	Props to assign to the fill materials of the resulting meshes.	undefined
strokeMeshProps	TresOptions	Props to assign to the resulting stroke meshes.	undefined
fillMeshProps	TresOptions	Props to assign to the resulting fill meshes.	undefined
depth	'renderOrder' | 'flat' | 'offsetZ' | number	Specify how SVG layers are to be rendered. (See "Depth")	renderOrder

Depth

The SVG component's depth prop allows you to specify how the 2D layers will be rendered in 3D. It accepts the following values:

'renderOrder'

Use case: Lone SVGs or applications that don't rely on stacked SVGs

This is the default depth option.

This value sets the materials' depthWrite to false and increments the mesh layers' renderOrder. This makes the SVG layers render dependably regardless of perspective.

Disadvantage: Scene objects may render out of order.

SVG layers with higher renderOrder will be rendered after (i.e., sometimes "on top of") other objects in the scene graph with a lower renderOrder. Depending on their settings, those other objects may render behind the SVG, even if they are closer to the camera.

'flat'

Use case: simple SVGs

This option sets the materials' depthWrite to false.

Disadvantage: SVG layers may render out of order.

Overlapping layers in an SVG may be drawn out of order, depending on viewing perspective.

'zOffset'

Use case: unscaled SVGs seen from the front

When this value is passed, the result is a 3D "stack" of mesh layers. A small space is added between each mesh layer in the "stack".

Disadvantage: "Bottom" of the "stack" is visible; layers may z-fight.

When seen from behind, the "bottom" of the mesh layer "stack" is visible. The space between the layers may be noticeable depending on viewing perspective and scale. The layers may z-fight, particularly if the SVG is scaled down.

number

Use case: SVGs seen from the front

This is the same as 'zOffset' but allows you to specify how much space is added between each layer, in order to eliminate z-fighting. For most use cases, this should be a value greater than 0.025 and less than 1.

Disadvantage: "Bottom" of the "stack" is visible.

Troubleshooting

WARNING

This is not a general-purpose SVG renderer. Many SVG features are unsupported.

Here are some things to try if you run into problems:

Error: "XML Parsing Error: unclosed token"

• In the SVG source, convert hex colors to rgb, e.g., convert #ff0000 to rgb(255, 0, 0).

Parts of the SVG render in the wrong order or disappear, depending on viewing angle

• In the component, change the depth prop.
• In the SVG source, use fill="none" rather than fill-opacity="0".

Parts of the SVG "z-fight"

• In the component, change the depth prop.
• Increase the distance between the component and other on-screen elements.

The SVG is not visible

• If importing an SVG, make sure the path is correct – check the console for loading errors.
• Try scaling the SVG component down, e.g., :scale="0.01".
• Try moving the SVG component up (+y), e.g., :position="[0,2,0]".