# CompassGizmo

component in `3d-tiles-renderer/r3f`

```js
import { CompassGizmo } from '3d-tiles-renderer/r3f';
```

Renders a compass overlay that rotates to indicate north based on the camera orientation relative
to the tileset ellipsoid. Must be a child of TilesRenderer. Remaining props are passed to the
root group element.

Example: Showing a compass that points north as the globe turns

```jsx
import { createRoot } from 'react-dom/client';
import { Canvas } from '@react-three/fiber';
import { TilesRenderer, TilesPlugin, GlobeControls, CompassGizmo } from '3d-tiles-renderer/r3f';
import { GeneratedSurfacePlugin, XYZTilesOverlay } from '3d-tiles-renderer/three/plugins';

const URL = 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}';
const overlay = new XYZTilesOverlay( { url: URL } );

function App() {

	return (
		<Canvas camera={ { position: [ 0, 0, 1.75e7 ] } }>
			<TilesRenderer group={ { rotation: [ - Math.PI / 2, 0, 0 ] } }>
				<TilesPlugin plugin={ GeneratedSurfacePlugin } args={ { overlay, applyOverlayTexture: true } } />
				<GlobeControls enableDamping />
				<CompassGizmo />
			</TilesRenderer>
		</Canvas>
	);

}

createRoot( document.getElementById( 'root' ) ).render( <App /> );
```

## Props

- `mode`, `string`, optional, default `'3d'`: Rotation mode: `'3d'` tracks full camera orientation, `'2d'` tracks yaw only.
- `scale`, `number`, optional, default `35`: Size of the compass in pixels.
- `margin`, `number | Array`, optional, default `10`: Margin from the bottom-right corner in pixels. Pass `[x, y]` to set each axis independently.
- `visible`, `boolean`, optional, default `true`: Whether the compass is rendered.
- `overrideRenderLoop`, `boolean`, optional: If true, renders the main scene before drawing the compass overlay.
- `children`, `ReactNode`, optional: Custom compass graphic replacing the default. Should fit within a -0.5 to 0.5 unit cube with +Y pointing north and +X pointing east.