@contentful/live-preview
Advanced tools
Preview SDK for both the field tagging connection + live content updates
Live preview SDK for both the inspector mode connection + live content updates by Contentful.
>=16.15.1To install live preview simply run one of the following commands.
yarn add @contentful/live-preview
or
npm install @contentful/live-preview
To establish a communication between your preview frontend and Contentful, you simply need to initialize the live preview SDK. This can be done by executing the following command:
import { ContentfulLivePreview } from '@contentful/live-preview';
...
ContentfulLivePreview.init({ locale: 'en-US'});
The init command also accepts a configuration object that allows you to customize your live preview SDK experience. The following options are available:
import { ContentfulLivePreview } from '@contentful/live-preview';
...
ContentfulLivePreview.init({
locale: 'set-your-locale-here' // This is required and allows you to set the locale once and have it reused throughout the preview
enableInspectorMode: false, // This allows you to toggle the inspector mode which is on by default
enableLiveUpdates: false, // This allows you to toggle the live updates which is on by default
debugMode: false, // This allows you to toggle the debug mode which is off by default
});
It is possible to override the locale you set in the init command for a more flexible workflow. If you need to override the locale you can do so either in the getProps command like below:
ContentfulLivePreview.getProps({ entryId: id, fieldId: 'title', locale: 'fr' });
You can also override it when using our useContentfulLiveUpdates hook like below:
import { useContentfulLiveUpdates } from '@contentful/live-preview/react';
// ...
const updated = useContentfulLiveUpdates(originalData, locale);
// ...
To use the inspector mode, you need to tag fields by adding the live preview data-attributes (data-contentful-entry-id, data-contentful-field-id) to the rendered HTML element output.
You can do this in React via our helper function.
The necessary styles for the live edit tags can be found in the @contentful/live-preview/style.css file.
import { ContentfulLivePreview } from '@contentful/live-preview';
import '@contentful/live-preview/style.css';
...
<h1 {...ContentfulLivePreview.getProps({ entryId: id, fieldId: 'title' })}>
{title}
</h1>
Live Updates allow you to make changes in your editor and see the updates in real time. The updates are only happening on the client-side and in the live preview environment of Contentful.
import { useContentfulLiveUpdates } from '@contentful/live-preview/react';
// ...
const updated = useContentfulLiveUpdates(originalData);
// ...
To use the Contentful Live Preview SDK with [Javascript], you can use the following steps to add it to an existing project.
yarn add @contentful/live-preview
or
npm install @contentful/live-preview
ContentfulLivePreview class' init function and add the stylesheet for field tagging as a stylesheet link.<!DOCTYPE html>
<html lang="en">
<head>
<title>Live Preview Example</title>
<link
rel="stylesheet"
type="text/css"
href="./node_modules/@contentful/live-preview/dist/style.css"
/>
<script type="module">
import { ContentfulLivePreview } from './node_modules/@contentful/live-preview/dist/index.js';
ContentfulLivePreview.init({ locale: 'en-US' });
</script>
</head>
<body></body>
</html>
data-contentful-entry-id, data-contentful-field-id) to your HTML element output.You can do this via our helper function.
The necessary styles for the live edit tags can be found in the @contentful/live-preview/style.css file.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Live Preview Example</title>
<link
rel="stylesheet"
type="text/css"
href="./node_modules/@contentful/live-preview/dist/style.css"
/>
<script type="module">
import { ContentfulLivePreview } from './node_modules/@contentful/live-preview/dist/index.js';
ContentfulLivePreview.init({ locale: 'en-US' });
const heading = document.getElementById('demo');
/*
* Example response
*
* const props = {
* 'data-contentful-field-id': 'fieldId',
* 'data-contentful-entry-id': 'entryId',
* 'data-contentful-locale': 'en-US',
* }
*/
const props = ContentfulLivePreview.getProps({ entryId: id, fieldId: title });
for (const [key, value] of Object.entries(props)) {
// change from hyphen to camelCase
const formattedName = key.split('data-')[1].replace(/-([a-z])/g, function (m, w) {
return w.toUpperCase();
});
heading.dataset[formattedName] = value;
}
</script>
</head>
<body>
<h1 id="demo">Title</h1>
</body>
</html>
4.To use the live updates feature you can make use of the subscribe function to listen to the data changes as shown below:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Live Preview Example</title>
<link
rel="stylesheet"
type="text/css"
href="./node_modules/@contentful/live-preview/dist/style.css"
/>
<script type="module">
import { ContentfulLivePreview } from './node_modules/@contentful/live-preview/dist/index.js';
const locale = 'en-US';
ContentfulLivePreview.init({ locale });
/**
* Subscribe to data changes from the Editor, returns a function to unsubscribe
* Will be called once initially for the restored data
*/
const unsubscribe = ContentfulLivePreview.subscribe({
data,
locale,
callback,
});
</script>
</head>
<body></body>
</html>
That's it! You should now be able to use the Contentful Live Preview SDK with vanilla JS.
You can find an example implementation in the examples/nextjs folder.
To use the Contentful Live Preview SDK with Next.js, you can either use one of the Contentful starter templates, or do the following steps to add it to an existing project.
yarn add @contentful/live-preview
or
npm install @contentful/live-preview
ContentfulLivePreviewProvider and add the stylesheet for field tagging inside _app.tsx or _app.js.
The ContentfulLivePreviewProvider accepts the same arguments as the init function.import '@contentful/live-preview/style.css';
import { ContentfulLivePreviewProvider } from '@contentful/live-preview/react';
const CustomApp = ({ Component, pageProps }) => (
<ContentfulLivePreviewProvider locale="en-US">
<Component {...pageProps}>
</ContentfulLivePreviewProvider>
)
This provides the possibility to only enable live updates and inspector mode inside draft mode:
import '@contentful/live-preview/style.css';
import { ContentfulLivePreviewProvider } from '@contentful/live-preview/react';
const CustomApp = ({ Component, pageProps }) => (
<ContentfulLivePreviewProvider locale="en-US" enableInspectorMode={pageProps.draftMode} enableLiveUpdates={pageProps.draftMode}>
<Component {...pageProps}>
</ContentfulLivePreviewProvider>
)
export default function BlogPost: ({ blogPost }) {
const inspectorProps = useContentfulInspectorMode()
// Live updates for this component
const data = useContentfulLiveUpdates(
blogPost
);
return (
<Section>
<Heading as="h1">{data.heading}</Heading>
{/* Text is tagged and can be clicked to open the editor */}
<Text
as="p"
{...inspectorProps({
entryId: data.sys.id,
fieldId: 'text',
})}>
{data.text}
</Text>
</Section>
);
}
It doesn't matter if the data is loaded with getServerSideProps, getStaticProps or if you load it in any other way.
It's necessary that the provided information touseContentfulLiveUpdatecontains thesys.idfor identification and only non-transformed fields can be updated.
(For GraphQL also the__typenameneeds to be provided)
Tip: If you want to tag multiple fields of an entry, you can also provide initial arguments to the hook:
export default function BlogPost: ({ blogPost }) {
const inspectorProps = useContentfulInspectorMode({ entryId: data.sys.id })
return (
<Section>
<Heading as="h1" {...inspectorProps({ fieldId: 'heading' })}>{data.heading}</Heading>
<Text as="p" {...inspectorProps({ fieldId: 'text' })}>
{data.text}
</Text>
</Section>
)
We suggest using the draft mode and the Content Preview API for the best experience.
For a full guide checkout this free course
That's it! You should now be able to use the Contentful live preview SDK with Next.js.
To use the Contentful live preview SDK with Gatsby, you can start with the gatsby starter contentful homepage
yarn add @contentful/live-preview
or
npm install @contentful/live-preview
import '@contentful/live-preview/style.css';
import React from 'react';
import { ContentfulLivePreviewProvider } from '@contentful/live-preview/react';
export const wrapRootElement = ({ element }) => (
<ContentfulLivePreviewProvider locale="en-US">{element}</ContentfulLivePreviewProvider>
);
interface HomepageHero implements Node & HomepageBlock {
id: ID!
contentful_id: String! # add this property
heading: String!
text: String
}
type ContentfulHomepageHero implements Node & HomepageHero & HomepageBlock @dontInfer {
id: ID!
contentful_id: String! # and also here
heading: String!
text: String
}
export const query = graphql`
fragment HomepageHeroContent on HomepageHero {
__typename
id
contentful_id # add this property
heading
text
}
`;
export default function Hero({ contentful_id, ...props }) {
const inspectorProps = useContentfulInspectorMode();
// Live updates for this component
const data = useContentfulLiveUpdates({
...props,
sys: { id: props.contentful_id },
});
return (
<Section>
<Heading as="h1">{data.heading}</Heading>
{/* Text is tagged and can be clicked to open the editor */}
<Text
as="p"
{...inspectorProps({
entryId: contentful_id,
fieldId: 'text',
})}>
{data.text}
</Text>
</Section>
);
}
That's it! You should now be able to use the Contentful live preview SDK with Gatsby.
We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.
Read our full Code of Conduct.
The live preview package is open source software licensed as MIT.
FAQs
Preview SDK for both the field tagging connection + live content updates
The npm package @contentful/live-preview receives a total of 40,775 weekly downloads. As such, @contentful/live-preview popularity was classified as popular.
We found that @contentful/live-preview demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.