Get started
Embedded Studio

Configure the host

Configure the host

MountayaStudioHost holds everything the editor shares: the client, the tool bus, the store and every setting. MountayaStudio inside it is the editor. Everything beyond client and itineraryId sits in a named group.

import { MountayaStudio, MountayaStudioHost } from "@mountaya/studio-react";

export const BrandedStudio = () => (
  <MountayaStudioHost
    appearance={{ theme: { primaryColor: "grape" }, tokens: { "--mtya-accent": "#7048e8" } }}
    client={mountaya}
    itineraryId={itineraryId}
  >
    <MountayaStudio />
  </MountayaStudioHost>
);
GroupWhat you set there
dataWho is reading, where they may write, the store and the query client.
behaviorYour handlers, confirm, notify, the co-pilot, the router and URL bindings.
appearanceColor scheme, density, --mtya-* tokens, the Mantine theme, the header.
i18nThe language, the locale, and both word bundles.
assetsIcons, layer pictures and activity silhouettes.
pluginsMenu items and controls a third party adds.

The Props tab lists every member of every group.

Keep the token fresh

Build the client once, over useSessionToken's session. The hook mints before the first request and renews the token before it expires, so nothing is rebuilt.

import { Mountaya } from "@mountaya/client/browser";
import { useSessionToken } from "@mountaya/client-react";
import { MountayaStudio, MountayaStudioHost } from "@mountaya/studio-react";
import { useState } from "react";

const mintSession = async () => {
  const response = await fetch("/api/mountaya-session");
  if (!response.ok) {
    throw new Error(`The session endpoint answered ${response.status}.`);
  }
  return response.json();
};

export const Studio = () => {
  const { session } = useSessionToken({ mint: mintSession });
  const [client] = useState(
    () => new Mountaya({ credential: { publishableKey, sessionToken: session } }),
  );

  return (
    <MountayaStudioHost client={client}>
      <MountayaStudio />
    </MountayaStudioHost>
  );
};

The host shows nothing until the first token lands. When another person signs in, mount the studio again under key={userId}, so their writes never ride the last person's token.

Choose which features show

The studio shows each member what your agreement covers and their role allows. Hand the host a viewer built by usePlatformViewer, which reads that answer from Mountaya.

import { createMemoryViewer } from "@mountaya/studio";
import { MountayaStudio, MountayaStudioHost, usePlatformViewer } from "@mountaya/studio-react";
import { QueryClient } from "@tanstack/react-query";
import { useState } from "react";

export const LicensedStudio = () => {
  const [cache] = useState(() => new QueryClient());
  const [person] = useState(() => createMemoryViewer({}, { getUserId: () => userId }));
  const { viewer } = usePlatformViewer({
    client: mountaya,
    organizationId,
    queryClient: cache,
    viewer: person,
  });

  return (
    <MountayaStudioHost client={mountaya} data={{ queryClient: cache, viewer }}>
      <MountayaStudio />
    </MountayaStudioHost>
  );
};
FeatureShows when
EditingThe token names a member with a write role in the organization.
Overlays and points of interestYour agreement lists them, and your safety rules allow them.
Publish, download, videoYour organization also holds Map Publishing.
Co-pilotYou state behavior.copilot. See co-pilot.
Live collaborationYou pass a session. See collaboration.
Embed wizardNever: embeds are configured in the Mountaya app.

Theme and translate it

Three layers style the studio, in the order they win: appearance.tokens, then appearance.theme, then your own CSS on a .mtya-* class. Words come from i18n.

import { frElementsStrings } from "@mountaya/elements/i18n/fr";
import { frStudioStrings } from "@mountaya/studio/strings/fr";
import { MountayaStudio, MountayaStudioHost, type StudioI18nConfig } from "@mountaya/studio-react";

const french: StudioI18nConfig = {
  language: "fr",
  studioStrings: { actions: { cancel: "Fermer" } },
  studioTranslations: { fr: frStudioStrings },
  translations: { fr: frElementsStrings },
};

export const FrenchStudio = () => (
  <MountayaStudioHost appearance={{ colorScheme: "dark" }} client={mountaya} i18n={french}>
    <MountayaStudio />
  </MountayaStudioHost>
);

The host's root is the studio's frame: dialogs fill it, not the window. Give it a height with appearance.style, and pass style={{ height: "100%" }} to MountayaStudio.

Show it read-only

MountayaStudioViewer is the same map and controls with every editing tool removed. Mount it under the host for a public page, on a token minted without user_id that keeps surface: "studio-embedded".

Arrange your own parts around the host

Chrome you mount beside MountayaStudio reads the same store and dispatches on the same bus. A sidebar next to the map drives that map.

Next steps

Last updated