@metapages/metapage-react

React components and hooks for building and using metaframes in your own projects.

There are two main use cases:

1. Your React app is a metaframe — your app runs is embedded inside a webpage, or a metapage and communicates via inputs/outputs
2. Your React app renders a metaframe — your app embeds an external metaframe URL in an iframe and exchanges data with it

Installation

npm i @metapages/metapage-react

---

1. Your React app is a metaframe

Use the provider components and hooks when your app itself is a metaframe — i.e. it will be loaded inside a metapage and needs to receive inputs and send outputs.

Providers

WithMetaframe

Context provider that initializes a Metaframe instance. Use with the useMetaframe hook.

WithMetaframeAndInputs

Context provider that initializes a Metaframe instance and tracks input updates as React state. Use with the useMetaframeAndInput hook. This is convenient but less efficient than managing listeners manually — if performance is critical, use WithMetaframe instead.

Hooks

Hook	Provider	Returns
useMetaframe	WithMetaframe	{ metaframe }
useMetaframeAndInput	WithMetaframeAndInputs	{ metaframe, inputs, setOutputs }

Example

Wrap your app in a provider:

import { WithMetaframe } from "@metapages/metapage-react";

render(
  <WithMetaframe>
    <App />
  </WithMetaframe>,
  document.getElementById("root")!
);

Then use the hook anywhere inside:

import { useMetaframe } from "@metapages/metapage-react";

export const App = () => {
  const metaframeObj = useMetaframe();

  // Option 1: respond to inputs via React state (convenient, less efficient)
  useEffect(() => {
    console.log("New inputs:", metaframeObj.inputs);
  }, [metaframeObj.inputs]);

  // Option 2: bind a listener directly (more efficient)
  useEffect(() => {
    if (!metaframeObj.metaframe) return;
    const disposer = metaframeObj.metaframe.onInput("someInputName", (value) => {
      console.log("Got input on someInputName:", value);
    });
    return () => disposer();
  }, [metaframeObj.metaframe]);

  // Set outputs
  if (metaframeObj.setOutputs) {
    metaframeObj.setOutputs({ some: "outputs" });
  }

  // Notify the metapage if your app modifies its own hash params
  useEffect(() => {
    if (metaframeObj.metaframe) {
      metaframeObj.metaframe.notifyOnHashUrlChange();
    }
  }, [metaframeObj.metaframe]);

  return <div>{JSON.stringify(metaframeObj.inputs)}</div>;
};

---

2. Your React app renders a metaframe

Use MetaframeStandaloneComponent when your app wants to embed and interact with an external metaframe. Your app is not itself a metaframe — it just renders one in an iframe and optionally sends it inputs or listens to its outputs.

MetaframeStandaloneComponent

Prop	Type	Description
url	string	(required) URL of the metaframe to embed
inputs	any	Data to send as inputs to the metaframe
onOutputs	(outputs: MetaframeInputMap) => void	Callback fired when the metaframe produces outputs
onUrlChange	(url: string) => void	Callback fired when the metaframe changes its own URL (e.g. hash params)
onMetapageCreation	(metapage: Metapage) => void	Callback for accessing the underlying Metapage instance (debugging)
debug	boolean	Enable debug logging
style	React.CSSProperties	Style for the iframe container
className	string	CSS class for the iframe element
classNameWrapper	string	CSS class for the wrapper div

Example: render a metaframe and exchange data

import { MetaframeStandaloneComponent } from "@metapages/metapage-react";

export const App = () => {
  const [outputs, setOutputs] = useState<any>(null);

  return (
    <div>
      <h1>Embedded metaframe</h1>

      <MetaframeStandaloneComponent
        url="https://js.mtfm.io/j/12a80d79290433e7d6cb38eedb1ebceeabfaca563c2fea13b0283fce6bf24b8b"
        inputs={{ code: 'console.log("hello")' }}
        onOutputs={(o) => setOutputs(o)}
        style={{ width: "100%", height: "500px" }}
      />

      {outputs && <pre>{JSON.stringify(outputs, null, 2)}</pre>}
    </div>
  );
};

Example: listen to URL changes

If the embedded metaframe modifies its own hash params (e.g. user interaction changes state encoded in the URL), you can track that:

<MetaframeStandaloneComponent
  url={metaframeUrl}
  onUrlChange={(newUrl) => {
    console.log("Metaframe URL changed to:", newUrl);
    // persist or react to the new URL
  }}
/>

---

Components reference

Export	Type	Use case
MetaframeStandaloneComponent	Component	Embed and render an external metaframe by URL
MetaframeIframe	Component	Low-level: render an iframe from a MetapageIFrameRpcClient instance
WithMetaframe	Provider	Your app is a metaframe (basic)
WithMetaframeAndInputs	Provider	Your app is a metaframe (with inputs as state)
useMetaframe	Hook	Access metaframe from WithMetaframe
useMetaframeAndInput	Hook	Access metaframe + inputs from WithMetaframeAndInputs