Internal Puck API
Puck exposes it’s internal API as PuckApi
for extending Puck with custom functionality within custom fields, compositional interfaces or UI overrides.
Accessing the internal API
You can access PuckApi
via two hooks:
usePuck
- returnsPuckApi
as part of your component render lifecycleuseGetPuck
- returns a function to access the latestPuckApi
at call time
Within the render lifecycle
To access the API within your render lifecycle, use the usePuck
hook. You can use a selector to limit re-rendering to a specific part of the API.
import { createUsePuck } from "@measured/puck";
const usePuck = createUsePuck();
const Example = () => {
// Use a selector so you only re-render when the selected type changes
const type = usePuck((s) => s.selectedItem?.type || "Nothing");
return <h2>{type} selected</h2>;
};
See the usePuck
docs for a full API reference.
Outside of the render lifecycle
Often it’s not necessary to re-render your component when the PuckApi changes. Puck provides the useGetPuck
hook for accessing the latest PuckApi
at call time.
import { useGetPuck } from "@measured/puck";
const Example = () => {
const getPuck = useGetPuck();
const handleClick = useCallback(() => {
// Get the latest PuckApi value
const { appState } = getPuck();
console.log(appState);
}, [getPuck]);
return <button onClick={handleClick}>Click me</button>;
};
See the useGetPuck
docs for a full API reference.
Usage in practice
Generally, you’ll want to combine this with composition, UI overrides or custom fields. PuckApi cannot currently be accessed outside of these contexts.
Here’s an example using the internal API to render the page data as JSON using composition:
import { Puck, createUsePuck } from "@measured/puck";
const usePuck = createUsePuck();
const JSONRenderer = () => {
const appState = usePuck((s) => s.appState);
return <div>{JSON.stringify(appState.data)}</div>;
};
export function Editor() {
return (
<Puck>
<JSONRenderer />
</Puck>
);
}