TresJS @tresjs/core

Declarative ThreeJS using Vue Components

• 💡 Build 3D scene as they were Vue components
• ⚡️ Powered by Vite
• 🥰 It brings all the updated features of ThreeJS right away regardless the version
• 🦾 Fully Typed

Tres (Spanish word for "three", pronounced /tres/ ) is a way of creating ThreeJS scenes with Vue components in a declarative fashion.

It's build on-top of a Vue Custom Renderer and it's powered by Vite.

The goal is to provide the Vue's community an easy way of building 3D scenes with Vue, always up to date with the latest ThreeJS features and with 0-to-none maintenance.

Installation

pnpm install @tresjs/core three

Docs

Checkout the docs

Demos

• Stackblitz Collection

Ecosystem

Package	Version
Tres
Cientos
Post-processing
Nuxt
TresLeches 🍰

Contribution

We are open to contributions, please read the contributing guide to get started.

Setup

pnpm install --shamefully-hoist

Playground

To run the small playground

pnpm run playground

Build lib

To build the core as library mode just use

pnpm run build

Docs

To run de docs in dev mode

pnpm run docs:dev

To build them

pnpm run docs:build

License

MIT

Sponsors

Changelog

4.3.5 (2025-05-16)

Bug Fixes

• make sure key is camelCase when reached else on conditional (#1011) (2902d05)

4.3.4 (2025-05-13)

Bug Fixes

• patchProp: harden props inference (#1006) (6cdf28b)
• revert improve type safety in retargeting proxy setter (#930) (0a95764)

Reverts

• Revert "fix: improve typing pixel ratio handling in setPixelRatio utility" (#929) (9e76010), closes #929

4.3.3 (2025-02-06)

Bug Fixes

• remove camera warning log on default camera creation (#916) (5d490b4)
• safely remove helpers in vDistanceTo and vLightHelper directives (#919) (f512b1a)
• typescript build issues utils (#924) (e9b7bf9)

4.3.2 (2025-01-03)

Features

• extend GlobalComponents interface to include 'primitive' component type (#896) (b78a6ff)
• update deps 20 12 24 (#887) (d377750)

Bug Fixes

• Add missing </UseLoader> closing tag. (#881) (e16ea32)
• function typo: fix typo in function name in composable (#858) (c186232)

4.3.1 (2024-10-13)

Bug Fixes

• 849 support Symbol keys in provide/inject (#850) (35125ce)

4.3.0 (2024-09-30)

Features

• add UseLoader component (471bd0d)
• app: 680 UseTexture composable as component (#757) (f01a897)
• pass all provides down to custom renderer (#806) (b4a3866)

Bug Fixes

• eslint (2ccd6c4)
• lint (f71eb37)
• lint (8f18558)
• rollback to v6 of @vue/devtools-api (#846) (fd3b599)
• type for useloader component props (a4bd590)

Reverts

• nodeOps: add check for null props (#829) (04b001b)
• useRenderer: add rendererPresets import (#839) (f944647)

4.2.10 (2024-09-04)

Bug Fixes

• 785 vscode intellisense autocompletion not getting tres components props (#809) (66c7ab5)

4.2.9 (2024-08-30)

Bug Fixes

• useLoader: remove array related logic for loaders (#808) (88cef1e)

4.2.8 (2024-08-30)

Bug Fixes

• use CubeTextureLoader correctly with array of files (#807) (38f05b0)

4.2.7 (2024-08-19)

4.2.6 (2024-08-15)

Bug Fixes

• 796 unmount the canvas component instant mount children again even if canvas is not mounted (#799) (9a20b52)

4.2.5 (2024-08-01)

Bug Fixes

• types: added Ref type to controls on ctx (415de94)

4.2.4 (2024-08-01)

Bug Fixes

• typescript issues (#794) (eecf608)

4.2.3 (2024-07-26)

Bug Fixes

• 792 directionallighthelpers breaks devtools (#793) (426acee), closes #533

4.2.2 (2024-07-24)

Bug Fixes

• remove on demand invalidation warning (#788) (eab74e6)

4.2.1 (2024-07-17)

Bug Fixes

• types: useLoader generics (#781) (b51d679)

4.2.0 (2024-07-14)

Features

• (devtools) add userData to inspectable properties (#740) (00bef33)
• TresCanvas: add dpr prop (#768) (8943cc3)

Bug Fixes

• attach detach (#749) (8c1c668)
• localstate for objects with events and manual register/unregister from nodeOps using ctx (#767) (9a53e60)
• primitive: implement as proxy to avoid breaking references (#764) (f637bf3)

4.1.0 (2024-07-05)

Features

• add useTresReady (#712) (15e3f07)

Bug Fixes

• deps: update dependency @vueuse/core to v10.10.1 (#735) (12e462d)
• group should recursive search for child elements (#728) (#731) (f09367b)

4.0.2 (2024-06-05)

Bug Fixes

• implement createComment and nextSibling node operations so that objects being v-if'd are not lost by Vue's runtime and incorrectly placed in the scene root (814d678)
• intersect only objects with events registered. (#714) (b320524)
• propogate events over previous intersections on pointerLeave and pointerOut (66264fc)

4.0.1 (2024-06-01)

Bug Fixes

• augmenting types for tres components for the nuxt module (#710) (c8a5b0d)

4.0.0 (2024-05-30)

Features

• release v4 (#490) (1ba17ee), closes #479 #488 #491 #497 #499 #498 #522 #514 #579 #602 #601 #608 #614 #529

4.0.0-rc.2 (2024-05-24)

Bug Fixes

• 686 useloop callback state missing controls (#687) (a41f532)
• manual rendering blank (#685) (0720d18)

4.0.0-rc.1 (2024-05-15)

Features

• 633 use loop (#673) (1b2fa70)

Bug Fixes

• make on* callbacks settable (#672) (ac152df)
• utils: reorder object disposal to avoid issue with Helper dispose methods (#683) (e5a2cef)

4.0.0-rc.0 (2024-04-25)

⚠ BREAKING CHANGES

• events: pointerevents manager and state (#529)

Features

• 499 better memory management (#606) (e98ca6d)
• devtools renderer improvements (#614) (cdf6b6f)
• events: pointerevents manager and state (#529) (b536ab1)

Bug Fixes

• do not change pierced props case (#608) (906f2e1)

4.0.0-next.2 (2024-03-27)

Bug Fixes

• refactor nodeOps to return methods at the end of the function (#602) (cd0c3bc)

4.0.0-next.1 (2024-03-18)

Features

• 140 on demand rendering (#497) (f688c64)
• 492 set tone mapping default to acesfilmictonemapping (#498) (c4547f9)
• 503 conditional rendering of primitives (#514) (79d8a76)
• 516 localstate for custom renderer node instances instead of userdata (#522) (08717ef)
• remove default camera warning (#499) (8bbafde)
• update to three v160 and vue v3.4 (#488) (5fad3b8)

Bug Fixes

• nodeOps is now a function (#579) (ddc229e)
• camera aspect (52dad5c)
• types: added Object3DEventMap to Object3D generics for point event handling (#491) (a63eb90)

4.0.0-next.0 (2023-12-22)

Features

• 474 vue chrome devtools plugin (#479) (224ab06)

4.0.0-next.2 (2024-03-27)

4.0.0-next.1 (2024-03-18)

• correct type exporting issues (#625) (8e52cf1)

3.9.0 (2024-04-24)

Features

• app: Add a new directive, v-rotate (ccf5313)

Bug Fixes

• deps: update dependency vue-router to v4.3.1 (#650) (9bbb676)

3.8.1 (2024-04-08)

Bug Fixes

• refactor nodeOps to return methods at the end of the function (#602) (cd0c3bc)

3.8.0 (2024-04-03)

Features

• allow custom loading manager to useTexture (#585) (a04c802), closes #432

Bug Fixes

• explicitely add @vue/devtools-api dep to package.json (#604) (98109af)
• useLogger: avoid string substitution in non-strings (3e2233c)
• useLogger: remove '<empty string>' from log, allow any args and string substitution (a482ebe)

3.7.0 (2024-01-29)

Features

• 140 on demand rendering (#497) (f688c64)
• 492 set tone mapping default to acesfilmictonemapping (#498) (c4547f9)
• 503 conditional rendering of primitives (#514) (79d8a76)
• 516 localstate for custom renderer node instances instead of userdata (#522) (08717ef)
• remove default camera warning (#499) (8bbafde)
• update to three v160 and vue v3.4 (#488) (5fad3b8)

Bug Fixes

• nodeOps is now a function (#579) (ddc229e)
• camera aspect (52dad5c)
• types: added Object3DEventMap to Object3D generics for point event handling (#491) (a63eb90)

4.0.0-next.0 (2023-12-22)

Features

• 474 vue chrome devtools plugin (#479) (224ab06)

3.7.0 (2024-01-29)

Features

• 474 vue chrome devtools plugin (#526) (0185bfa)
• 524 feat add directives to core (#525) (5268e9f)

Bug Fixes

• docs: change image path to silence warning (#519) (280d248)

3.6.1 (2024-01-16)

Bug Fixes

• correct minor typos (#438) (341faac), closes #452
• incorrect MathRepresentation type (#456) (314b088)
• usetrescontextprovider: fixed rendering issues caused when resize is triggered (#512) (a16b12b), closes #511

3.6.0 (2023-12-12)

Features

• enable devtools (#465) (d61df05)

3.6.0-next.0 (2023-12-06)

Features

• devtools hook on window object (df96c1f)

3.5.2 (2023-12-12)

Bug Fixes

• force memory free allocation when disposing materials and geometries (#463) (1ef3533)

3.5.1 (2023-11-28)

3.5.0 (2023-11-05)

Features

• useSeek: Add seekAll and seekAllByName methods to useSeek composable (#433) (ef905a3)

Bug Fixes

• types-(fix-#427): vueprops change ref to vnoderef and key add number and symbol (#428) (45aeafd), closes fix-#427 #427

3.4.1 (2023-10-19)

Bug Fixes

• passing class and style attrs only (#423) (8fd991a)

3.4.0 (2023-10-19)

Features

• announce cientos 3.5.0 (#417) (064806f)

Bug Fixes

• pass attrs down to canvas (#422) (aeab3e8)

3.3.0 (2023-10-02)

Features

• context (TresContext) is now exposed from TresCanvas (#404) (838d779)

Bug Fixes

• core: made v-if work again (#409) (0d00545)

3.3.0-next.0 (2023-09-29)

Features

• context (TresContext) is now exposed from TresCanvas (#404) (838d779)

Bug Fixes

• made v-if work again (277e901)

3.2.3 (2023-09-22)

Bug Fixes

• types: useTexture() (#401) (20ffa4b)

3.2.2 (2023-09-16)

Bug Fixes

• ensure scene as parent fallback for helpers (#397) (d63b028)
• made reactivity of camera prop on TresCanvas work again (#396) (990612d)
• useTexture docs detail (#395) (158d4c3)

3.2.1 (2023-09-11)

Bug Fixes

• proxy app context (#394) (2301269)

3.2.1-next.4 (2023-09-11)

Reverts

• Revert "chore: fix lint" (f53fba9)

3.2.1-next.3 (2023-09-11)

Bug Fixes

• revert object assign usage for setting app in appContext (889e022)

3.2.1-next.2 (2023-09-11)

Bug Fixes

• explicitely set app context app (c2a758f)

3.2.1-next.1 (2023-09-11)

Bug Fixes

• object assign approach for inner app context (3a6dc31)

3.2.1-next.0 (2023-09-11)

Bug Fixes

• proxy app context (128e3a5)

3.2.0 (2023-09-06)

Features

• objects blocking pointer event (#388) (03ab2e1)
• renamed useCamera composable methods to prevent confusion (#380) (58feabd)

Bug Fixes

• removed boolean prop defaults from TresCanvas (#384) (bb5fca5)

3.1.1 (2023-08-26)

Bug Fixes

• removing z-index from canvas (#382) (ac096f7)

3.1.0 (2023-08-23)

Features

• use render instead of createApp (#375) (9461a78)

Bug Fixes

• added logic on pathProps to re-instance nodes once args change (#367) (453b031)
• added revision version to apply useLegacyLights only if neccesary (#373) (dee4b97)
• args should be empty when args was falsy (#369) (81b7914)
• instances re-instancing when not needed (#374) (f2ae46b)

3.0.1 (2023-07-29)

Bug Fixes

• added controls and extend to state context (#355) (c2540a5)

3.0.0 (2023-07-29)

⚠ BREAKING CHANGES

• UseTres is now useTresContext. Instead of using a store like in v2, we now use a context provider based on provide/inject.

Features

• 331 new context for state (#333) (0e66f43), closes #340

Documentation

• explain state breaking changes (4757da9)

2.4.2 (2023-07-14)

Bug Fixes

• add raycaster to state (#347) (c45d4c3)

2.4.1 (2023-07-13)

Bug Fixes

• add app context to state (#346) (197f258)
• change internal Scene component name to force rendering (#330) (780743c)
• fake a VNodeRef on types to accept strings and null (#344) (c069f64)
• prop types on TresCanvas (#326) (309584a)

2.4.0 (2023-06-28)

Features

• export vue compiler options for Tres custom renderer (#324) (66716d5)

Bug Fixes

• temporaly cast the disableRender prop (#322) (9cc63d2)

2.3.0 (2023-06-22)

Features

• export utility functions (#315) (7580c77)

2.2.0 (2023-06-19)

Features

• removed useCamera logic from nodeOps (#308) (e9509ba)

Bug Fixes

• banner image link (b793c77)
• main button colors (3aab827)
• raycaster does not work properly when scene is not in full screen (#304) (20a5b9e)

2.1.3 (2023-06-14)

Bug Fixes

• deps: update dependency @alvarosabu/utils to v3 (97a9950)
• deps: update dependency @tresjs/cientos to v2.1.3 (cae506d)
• extend GlobalComponents rather than replacing (70b3717)
• message canvas 0 height false positives (bdfbdfe)

2.1.2 (2023-05-26)

Bug Fixes

• added scene fallback as parent for controls (e986f9c)

2.1.1 (2023-05-22)

2.1.0 (2023-05-22)

Features

• mighty sexy runtime types (97a5b64)

Bug Fixes

• docs dev and build (7106cf9)
• package exports (7c9e41a)
• package exports types (6fa3e09)
• pnpm workspace structure (e8300d6)
• re-mount custom renderer manually on HMR (029542e)

2.0.0 (2023-05-12)

2.0.0-rc.4 (2023-05-09)

Bug Fixes

• only set default camera settings to first camera (7f1e7cd)

2.0.0-rc.3 (2023-05-09)

Bug Fixes

• akwardly added fog and fixed also typing (e256768)
• colorspace types (27e10e9)
• disabling pushing more than one camera on nodeOpts (57a07bf)

2.0.0-rc.2 (2023-05-03)

Bug Fixes

• updated breaking changes of three v152 color maangement (1e47a5f)

2.0.0-rc.1 (2023-05-03)

2.0.0-rc.0 (2023-05-03)

2.0.0-beta.13 (2023-04-27)

Features

• add manual camera prop to canvas (588a3fc)

2.0.0-beta.12 (2023-04-25)

Bug Fixes

• avoid assigning args as BufferAttribute to BufferGeometry (1cc67b0)
• deps: update dependency three to ^0.151.0 (6f0e80c)

2.0.0-beta.11 (2023-04-20)

Bug Fixes

• optional chaining on insert vnodes (c2dcf52)

Reverts

• Revert "edit getting-started.md" (fcc6900)

2.0.0-beta.10 (2023-04-19)

Bug Fixes

• core: fixed #209 (9648935)

2.0.0-beta.9 (2023-04-18)

Bug Fixes

• incorrect implementation of disable render on canvas (2442935)

2.0.0-beta.8 (2023-04-17)

Features

• add disable render prop for postprocessing (b2fd557)

2.0.0-beta.7 (2023-04-15)

Bug Fixes

• remove object assign for non primitive (f9e0d4b)

2.0.0-beta.6 (2023-04-15)

2.0.0-beta.5 (2023-04-14)

Features

• core: fixed nodeOps remove test (2706f48)
• core: fixed nodeOps remove test (this time correctly 😉) (f5fca28)
• core: made custom renderer determine whether materials and geometries should be disposed (36c8cf5)
• core: made custom renderer traverse the scene tree to dispose obsolete materials and geometries (cae21b1)
• first try concerning conditional rendering of components (31bdd96)
• primitive (ab63e14)

Bug Fixes

• @pointer-move events (b451862)
• correct casing of key names when pierced props (b6a808f)

2.0.0-beta.4 (2023-04-06)

Bug Fixes

• optional chaining on object pointer events (421a7d5)

2.0.0-beta.3 (2023-04-06)

Bug Fixes

• added default position and direction to camera if props are not passed (63a340f)
• tres-canvas window-size now support 'true' string (a63e33f)

2.0.0-beta.2 (2023-04-05)

Bug Fixes

• move raycaster logic from nodeOps to TresCanvas (d2200ae)
• raycaster events listener on canvas rather than windows (bfe82b0)

2.0.0-beta.1 (2023-04-04)

Features

• expose state from TresCanvas (eeeff2e)

2.0.0-beta.0 (2023-04-04)

Features

• cleanup of obsolete code (f55ef36)
• core: performance improvement concerning raycaster (#139) (597e917)
• use tres provider and context (46cdd00)

2.0.0-alpha.6 (2023-03-30)

Features

• add alphaMap to useTexture (f66c363)
• add matcap to useTexture (ce374d6)
• adding warning when canvas parent height is 0px (4224103)

Bug Fixes

• removed key split on buffer geometry attributes (a29cb2b)

2.0.0-alpha.5 (2023-03-28)

Features

• useSeek composable (bd00001)

2.0.0-alpha.4 (2023-03-27)

Bug Fixes

• removing resetState and going for more granular approach of disposal (6f1e38b)
• reset state on unmounted (dbbaee7)

2.0.0-alpha.3 (2023-03-26)

Bug Fixes

• ensure parent for nodeOps target when key is a function (c07d963)

2.0.0-alpha.2 (2023-03-23)

Features

• buffergeometry setAttribute logic (beee7b3)

2.0.0-alpha.1 (2023-03-22)

Bug Fixes

• set scene to state (1ead941)

2.0.0-alpha.0 (2023-03-22)

Features

• cientos: better typ support useEnvironment (821b6a6)
• cientos: correctly typed Text3D (61efbfb)
• cientos: orbit controls typed (e38e699)
• cientos: shapes types (aa7361b)
• cientos: typed usePamCameraMouse (07609be)
• core: adding composables to the solution (9a3f8bb)
• core: auto generated tres component types (7430d2c)
• core: cleaning up a little bit (8bdd825)
• core: export useLogger (4ad1a3e)
• core: fixing black screen (f4f198c)
• core: function props and demos updated (fa072cd)
• core: nice warning for camera at [0,0,0] (71eff1b)
• core: provide inject worked again (2390ec1)
• core: re-structure and tres custom renderer base (aad0953)
• core: tres components typing auto generated (6736b4c)
• core: types for TresCanvas (42ee984)
• core: v-if working on custom renderer (e19da3a)
• createTres wrapper for mounting options (d480b36)

Bug Fixes

• cientos: added default props to orbit controls (68d8673)
• cientos: cone props (5f20368)
• cientos: remove unused extend (5d5b487)
• core: added handleHMR update (594ab73)
• core: fixed type issues (bd4be33)
• core: nodeOps no op (9044c99)
• useTexture to show indentation for code snippet (e983c5d)