useContent

This hook fetches the content of a Slot, serving as the imperative equivalent of the <Slot> component.

Signature

This hook has the following signature:

function useContent<T extends SlotId>(id: T, options?: FetchOptions): SlotContent<T>;

The return is the content of the slot.

Example

Here is an example of how to use this hook:

import {useContent} from '@croct/plug-next';
export function HomeHero() {  const content = useContent('home-hero');
  return (    <div>      <strong>{content.title}</strong>      <p>{content.subtitle}</p>      <a href={content.button.link}>{content.button.label}</a>    </div>  );}

Parameters

id

string

The ID of the slot to fetch.

You can specify the version of the slot by passing a versioned ID in the form id@version. For example, passing home-hero@1 will fetch the content for the home-hero slot in version 1. Not specifying a version number is the same as passing home-hero@latest, which will load the content for the latest version.

Best practice

Always specify a version to ensure the front end receives content with the expected structure despite future schema changes.

For more information, see Slot versioning.

options(optional)

object

The fetch options.

initial(optional)

JSON

An initial value to render while loading the actual value.

Auto-provided

If you are using the Croct CLI, you do not need to set a initial unless you want to use a different one.

This value is required for server-side rendering. For client-side rendering, not specifying this value will cause rendering to suspend, requiring a <Suspense> boundary to handle the loading state. With Croct CLI, initial content is added automatically.

fallback(optional)

JSON

A fallback value to render in case of an error.

Auto-provided

If you are using the Croct CLI, you do not need to set a fallback unless you want to use a different one.

If not specified, an error is thrown on failure.

expiration(optional)

number

The cache expiration time in milliseconds, extended on every render.

If negative, the cache never expires. By default, the cache expires after 60 seconds.

The SDK caches the result of the evaluation to prevent network requests on concurrent renders and re-renders.

Default:60000

cacheKey(optional)

string

A unique key to identify the cache entry.

By default, the cache key is the ID of the slot. However, you can specify a unique cache key to force re-evaluation even if the query and attributes are the same.

staleWhileLoading(optional)

boolean

Whether to use the previous content while re-fetching the content.

By default, the hook always returns the initial content or suspends while loading new content.

If this option is enabled, the behaviour changes as follows:

• On the first render, it either returns the initial content or suspends while fetching updated data.
• If the cache key or any other property that affects the content changes, it returns the previous content while fetching the new content.
• When the new content is available, it renders again with the updated content.

Default:false

preferredLocale(optional)

string

The locale code to fetch the content.

Auto-configuration

The SDK auto-detects the preferred locale if you are using Internationalized Routing, so you do not need to specify this option unless you want to override it.

The code consists of a two-part string that specifies the language and, optionally, the country. For example, en represents English, en-us stands for English (United States), and pt-br for Portuguese (Brazil). It is case-insensitive and supports both hyphens and underscores as separators to accommodate the different conventions used by browsers, libraries, and other systems.

If no content is available in the preferred locale, the default locale content is returned instead.

Default:default locale

timeout(optional)

number

The maximum fetch time in milliseconds.

Environment variable

You can also set this option by defining the environment variable NEXT_PUBLIC_CROCT_DEFAULT_FETCH_TIMEOUT.

Once reached, the SDK will abort the request and reject the promise with a timeout error.

attributes(optional)

object

The map of attributes to inject in the evaluation context.

The attributes can be referenced in audience conditions using the context variable. For example, suppose you pass the following attributes:

{cities: ["New York", "San Francisco"]}

You can then reference them in queries like:

context's cities include location's cityName

For more information, see Context variables.

The following restrictions apply to the attributes:

• Up to 30 entries and 5 levels deep
• Keys can be either numbers or non-empty strings with a maximum length of 50 characters
• Values can be null, numbers, booleans, strings (up to 50 characters), or nested maps
• Nested maps follow the same constraints for keys and values