asthree-react

A React component that renders 3D models with a real-time ASCII art effect. Drop it into any React project and get an interactive, customizable ASCII render of any .glb model — no configuration required.

Website & Docs · Live Editor (Lab) · npm

Installation

npm i @defu13/asthree-react

Peer dependencies

Make sure these are installed in your project:

npm i react react-dom three @react-three/fiber @react-three/drei @react-three/postprocessing postprocessing

Quick start

You'll need two assets in your project's public folder:

• HDR lighting file — download a free one from Poly Haven and place it at public/hdr/studio.hdr
• 3D model — download a free .glb model from Sketchfab and place it at public/models/model.glb

import { AsthreeRender } from "@defu13/asthree-react";

export default function App() {
    return (
        <div className="h-screen w-screen">
            <AsthreeRender model="/models/model.glb" hdr="/hdr/studio.hdr" />
        </div>
    );
}

For the full walkthrough, see the Installation and Usage guides.

Props

| Prop | Type | Default | Description | |---|---|---|---| | model | string | "/models/model.glb" | Path or URL to a .glb model file | | hdr | string | "/hdr/studio.hdr" | Path or URL to a .hdr lighting file | | preset | string | — | Preset code generated by the Asthree Lab | | settings | object | — | Settings object (alternative to preset) | | width | string | "100%" | Canvas width | | height | string | "100%" | Canvas height | | enableOrbit | boolean | true | Allow rotating the model by dragging | | enableZoom | boolean | true | Allow zooming with the scroll wheel or pinch gesture |

Full reference: Props

Using presets

The easiest way to configure the render is through the Asthree Lab — a visual editor that lets you adjust every parameter in real time and generates a short preset code you can copy and paste directly into the preset prop.

<AsthreeRender
    model="/models/model.glb"
    hdr="/hdr/studio.hdr"
    preset="AQQh_zNmGQwfAfQiANI"
/>

The preset encodes only the values that differ from the defaults, so codes stay short even with many customizations. See Presets for details.

Manual settings

If you prefer to pass settings as an object instead of a preset string:

<AsthreeRender
    model="/models/model.glb"
    hdr="/hdr/studio.hdr"
    settings={{
        ascii: {
            cellSize: 12,
            tintColor: "#FF3366",
            glow: true,
            glowIntensity: 5,
        },
        model: {
            autoRotate: true,
            autoRotateSpeed: 0.3,
        },
    }}
/>

Partial objects are merged with the defaults, so you only need to specify what you want to change.

Disabling interaction

// Static render — no orbit, no zoom
<AsthreeRender
    model="/models/model.glb"
    hdr="/hdr/studio.hdr"
    preset="AQQh_zNmGQwfAfQiANI"
    enableOrbit={false}
    enableZoom={false}
/>

Default configuration

The following is the complete default settings object. When using the settings prop, any value you omit will fall back to these defaults.

{
    camera: {
        position: { x: 0, y: 0, z: 5 },
        target:   { x: 0, y: 0, z: 0 },
        fov: 50,
        orbit: {
            theta:  0,    // horizontal rotation
            phi:    1.5,  // vertical rotation
            radius: 4.5,  // distance from target
        },
    },

    model: {
        scale:           2,
        position:        { x: 0, y: 0, z: 0 },
        rotation:        { x: 0, y: 0, z: 0 },
        tilt:            { forward: 0, left: 0 },
        autoRotate:      true,
        autoRotateSpeed: 0.2,
    },

    lights: {
        ambient: 0,
        directional1: {
            position:  [2, 3.5, 6],
            intensity: 3,
        },
        directional2: {
            position:  [-2, 1.5, 4],
            intensity: 0.35,
        },
    },

    ascii: {
        style:            "standard", // "standard" | "blocks" | "shade" | "thin" | "dots"
        cellSize:         9,
        invert:           true,
        color:            true,
        volumeShading:    true,
        shadingIntensity: 0.5,
        glow:             true,
        glowIntensity:    7,
        glowSize:         3,
        tintColor:        "#6B51F0",
    },

    postfx: {
        contrastAdjust:   1.5,
        brightnessAdjust: 0.2,
    },
}

Tech stack

• React Three Fiber — React renderer for Three.js
• Three.js — 3D engine
• postprocessing — Post-processing effects pipeline
• Zustand — Lightweight state management

Links

• Website & full documentation
• Live editor — Asthree Lab
• GitHub repository
• npm package

License

MIT © Yubal De Fuente