Objects
Model
External 3D model object with loader selection, fit controls, centering, and optional CSS material override.
Model
model is the object type for external 3D assets such as .glb.
Use it when the shape already exists as authored geometry and you want StringTune-3D to place, fit, light, and optionally restyle that asset inside the same CSS-first runtime.
When to use it
Use model when:
- the visual source of truth is already a 3D file
- primitives are too abstract
- you need authored topology, silhouettes, or details
- the scene should still be positioned and animated from the DOM layer
Runtime contract
Activation
<div string="3d" string-3d="model"></div>
Attributes
| Attribute | Default | Effect |
|---|---|---|
string-3d-model | empty | Model URL |
string-3d-model-loader | empty | Loader type key resolved by the provider |
string-3d-model-scale | 1 | Extra model scale multiplier |
string-3d-model-fit | contain | Fit mode |
string-3d-model-center | false | Recenters imported content around its bounds |
string-3d-model-texture-base | empty | Base path for texture remapping |
string-3d-model-textures | empty | Texture remap table |
Shared CSS inputs
Models still participate in the normal transform and material contract. If CSS material properties are present, the imported model may be visually overridden through the same surface used by primitives.
Example
<div
string="3d"
string-3d="model"
string-3d-model="/models/robot.glb"
string-3d-model-loader="gltf"
string-3d-model-fit="contain"
string-3d-model-center="true"
style="
width: 260px;
height: 260px;
--rotate-y: 24;
--translate-z: 60;
--material-color: #f5f0e8;
"
></div>
Provider requirement
The provider must know how to load the model type you reference. For example, a GLTF workflow usually means passing a GLTF loader into the provider.
import * as THREE from 'three';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { String3D, ThreeJSProvider } from 'string-tune-3d';
String3D.setProvider(new ThreeJSProvider(THREE, { gltf: GLTFLoader }));
What the runtime does
- The object asks the active engine for a loader matching the selected loader key.
- The imported root is fitted to the element box according to the selected fit mode.
- Optional centering is applied after bounds are known.
- Material overrides are not a separate mode. They are inferred from the CSS values you provide.
Practical note
Keep model for authored forms and keep scene logic outside the asset when possible. It is usually better to animate the host element through CSS variables than to bury motion inside the model file.