<MeshLineMaterial>

Used in combination with <MeshLineGeometry> to create a line formed of a strip of billboarded triangles, based on THREE.MeshLine.

Show Code

• App.svelte
• Scene.svelte

<script lang="ts">
  import { Canvas } from '@threlte/core'
  import Scene from './Scene.svelte'
</script>

<div>
  <Canvas>
    <Scene />
  </Canvas>
</div>

<style>
  div {
    height: 100%;
  }
</style>

<script>
  import { T, useTask } from '@threlte/core'
  import {
    MeshLineMaterial,
    MeshLineGeometry,
    Grid,
    OrbitControls,
    useTexture
  } from '@threlte/extras'
  import { Vector3, CatmullRomCurve3, Color } from 'three'

  // create a smooth curve from 4 points
  const curve = new CatmullRomCurve3([
    new Vector3(-3, 0, 0),
    new Vector3(-1, 1, -1),
    new Vector3(1, -1, 1),
    new Vector3(3, 0, 0)
  ])

  // convert curve to an array of 100 points
  const points = curve.getPoints(100)

  let width = $state(0.5)
  let dashOffset = $state(0)
  let color = $state('#fe3d00')
  const orange = new Color('#fe3d00')
  const purple = new Color('#9800fe')
  const c = new Color()

  useTask((delta) => {
    // every frame we:
    // increase the dash offset
    dashOffset += delta / 2
    // transition between two colors
    color = `#${c.lerpColors(orange, purple, Math.sin(dashOffset * 2) / 2 + 0.5).getHexString()}`
    // shrink and grow the line width
    width = Math.sin(dashOffset * 2) / 5 + 0.3
  })
</script>

<T.Mesh
  position.y={3}
  scale={2}
>
  <MeshLineGeometry {points} />

  <MeshLineMaterial
    {width}
    {color}
    dashArray={0.5}
    dashRatio={0.5}
    {dashOffset}
    transparent
    depthTest={false}
  />
</T.Mesh>

<T.PerspectiveCamera
  makeDefault
  oncreate={(ref) => {
    ref.position.set(10, 3, 10)
  }}
>
  <OrbitControls
    autoRotate={true}
    autoRotateSpeed={2}
    enableDamping
    target.y={2}
  />
</T.PerspectiveCamera>

<Grid
  gridSize={[10, 10]}
  cellColor={'#46536b'}
  sectionThickness={0}
/>

Usage

This component works by taking a line geometry from <MeshLineGeometry> and projecting and expanding the vertices in screen space. Both <MeshLineMaterial> and <MeshLineGeometry> need belong to the same parent mesh.

Example

<script>
  const points = [new Vector3(-5, 1, 0), new Vector3(0, 1, 0), new Vector3(5, 1, 0)]
</script>

<T.Mesh>
  <MeshLineGeometry {points} />
  <MeshLineMaterial
    width={0.5}
    color="#fe3d00"
  />
</T.Mesh>

Width and color

By default the line will be white and have a width of 1. The width property will use world units and scale correctly with other objects in your scene. If you would like the line to be a fixed size regardless of distance from the camera you can set the attenuate property to false.

Opacity and dashes

Just like other materials in Three.js you need to set transparent to true for opacity to have any effect. You must also set transparent to true for if you are using dashed lines.

You can use a combination of dashArray, dashRatio and dashOffset to create dashed lines.

If you’re rendering transparent lines, dashed lines or lines with an alpha map you can avoid issues where the line overlaps itself by setting depthTest to false.

Alpha map

You can pass a texture to the alphaMap property to use as an alpha mask along the length of the line, where black is invisible and white is visible. In the example below we load a paint brush texture with the useTexture hook.

Show Code

• App.svelte
• Scene.svelte

<script lang="ts">
  import { Canvas } from '@threlte/core'
  import Scene from './Scene.svelte'
</script>

<div>
  <Canvas>
    <Scene />
  </Canvas>
</div>

<style>
  div {
    height: 100%;
  }
</style>

<script>
  import { T } from '@threlte/core'
  import {
    Grid,
    MeshLineGeometry,
    MeshLineMaterial,
    OrbitControls,
    useTexture
  } from '@threlte/extras'
  import { CubicBezierCurve3, DoubleSide, Vector3 } from 'three'

  const texture = useTexture('/brush-texture.png')

  // create a smooth bezier curve
  const curve = new CubicBezierCurve3(
    new Vector3(-5, 0, 0),
    new Vector3(-5, 7, 0),
    new Vector3(5, 7, 0),
    new Vector3(5, 0, 0)
  )

  // convert curve to an array of 100 points
  const points = curve.getPoints(100)
</script>

<T.Mesh rotation.z={-0.1}>
  <MeshLineGeometry {points} />
  {#await texture then alphaMap}
    <MeshLineMaterial
      width={1}
      color={'#fe3d00'}
      transparent
      depthTest={false}
      {alphaMap}
    />
  {/await}
</T.Mesh>

{#await texture then map}
  <T.Mesh
    position.y={2}
    scale={2}
  >
    <T.PlaneGeometry />
    <T.MeshBasicMaterial
      {map}
      side={DoubleSide}
    />
  </T.Mesh>
{/await}

<T.PerspectiveCamera
  makeDefault
  oncreate={(ref) => {
    ref.position.set(0, 3, 10)
  }}
>
  <OrbitControls
    autoRotateSpeed={2}
    enableDamping
    target.y={2}
  />
</T.PerspectiveCamera>

<Grid
  gridSize={[10, 10]}
  cellColor={'#46536b'}
  sectionThickness={0}
/>

Component Signature

<MeshLineMaterial> extends < T . ShaderMaterial > and supports all its props, snippets, bindings and events.

Props

name

type

required

default

description

---

attenuate

boolean

no

true

Set to false to make the line width constant regardless distance.

---

color

ColorRepresentation

no

'#ffffff'

The color of the line.

---

dashArray

number

no

0

The length and space between dashes. 0 = no dash.

---

dashOffset

number

no

0

The location where the dash will begin. Ideal to animate the line.

---

dashRatio

number

no

0

The ratio between the visible and non-visible sections of the dash.

---

opacity

number

no

1

The opacity of the line. For values less than 1 transparent must be set to true.

---

scaleDown

number

no

0

The amount to scale down the line when points are close together. 0 = don't scale.

---

width

number

no

1

The width of the line. If attenuate is true it's world units, otherwise it's screen pixels.