# Custom content blocks

Source: https://dev.arcxp.com/themes/how-to-guides/custom-content-blocks/

How to create and configure custom content blocks in Arc Themes

Arc Themes 4.2.0 introduces two content source blocks for fetching documents from custom schemas defined in Content API v5\. Use the **schema item** block to retrieve a single document by ID, or the **schema feed** block to query and paginate across multiple documents in a schema. Together, they provide flexible access to any custom content types for your Arc XP organization.

## Prerequisites

- Arc Themes version 4.2.0 or above
- A valid `ARC_ACCESS_TOKEN` configured in your Fusion environment
- One or more custom schemas in your org/environment with published documents

## Schema item content source

The `@wpmedia/schema-item-content-source-block` is a content source that fetches a single document by its ID from a specified custom schema. It calls the Content API v5 endpoint `/content/v5/search/schemas/by-id/` and returns the document data directly.

### Configuration

The block accepts two parameters in PageBuilder:

| Parameter                    | Type | Required | Description                                        |
| ---------------------------- | ---- | -------- | -------------------------------------------------- |
| **Document ID** (id)         | text | Yes      | The unique identifier of the document to retrieve. |
| **Schema Name** (schemaName) | text | Yes      | The name of the custom schema to query against.    |

Responses are cached with a TTL of 300 seconds (5 minutes).

### Usage

To use this content source in a block:

1. In PageBuilder, add a feature block to your page that accepts a content source.
2. Select **schema-item** as the content source.
3. Enter the **Document ID** and **Schema Name** for the custom schema document you want to display.

The content source returns a document object with this structure:

```json
{
  "data": {
    "schema_content": { /* your custom schema fields */ },
    "schema_name": "your-schema",
    "document_id": "ABC123...",
    "first_publish_date": "2026-04-07T21:20:09.484Z",
    "publish_date": "2026-04-08T21:28:38.677Z",
    "created_date": "2026-04-07T21:13:26.751Z"
  }
}
```

The `schema_content` object contains the fields defined by your custom schema. The surrounding metadata (`document_id`, dates) is consistent across all schemas.

### Example feature block

The following skeleton shows a minimal feature block that renders content from the schema item source. Use it as a starting point for building custom detail pages. For use on templates, this block includes an option to inherit the global content, so it can be used to render a custom schema document without requiring a designated page for each schema item. In order for global content to be inherited, the resolver must be configured to return a document with the custom schema.

```jsx
import React from "react";
import PropTypes from "@arc-fusion/prop-types";
import { useContent } from "fusion:content";
import { useFusionContext } from "fusion:context";

const SchemaItemFeature = ({ customFields }) => {
  const { arcSite, globalContent } = useFusionContext();

  const customContent = useContent(
    customFields?.contentConfig
      ? {
          source: customFields.contentConfig.contentService,
          query: customFields.contentConfig.contentConfigValues,
        }
      : {},
  );

  const content = customFields?.inheritGlobalContent ? globalContent : customContent;
  const schemaContent = content?.data?.schema_content;

  if (!schemaContent) return null;

  // Replace with your own schema fields and markup
  return (
    <article>
      <h1>{schemaContent.title}</h1>
      <p>{schemaContent.description}</p>
    </article>
  );
};

SchemaItemFeature.propTypes = {
  customFields: PropTypes.shape({
    contentConfig: PropTypes.contentConfig().tag({
      group: "Configure Content",
      label: "Schema Item Source",
    }),
    inheritGlobalContent: PropTypes.bool.tag({
      name: "Inherit from global content",
      defaultValue: false,
      group: "Configure Content",
    }),
  }),
};

SchemaItemFeature.label = "Schema Item Feature – Arc Block";

export default SchemaItemFeature;
```

## Schema feed content source

The `@wpmedia/schema-feed-content-source-block` is a content source that queries multiple documents from a custom schema. It calls the Content API v5 endpoint `/content/v5/search/schemas/` and supports sorting, filtering, and pagination.

### Configuration

| Parameter                    | Type   | Required | Default | Description                                       |
| ---------------------------- | ------ | -------- | ------- | ------------------------------------------------- |
| **Schema Name** (schemaName) | text   | Yes      | —       | The name of the custom schema to query.           |
| **Sort By** (sortBy)         | text   | No       | —       | Field name to sort results by (descending order). |
| **Query** (query)            | text   | No       | —       | Search query to filter results.                   |
| **Size** (size)              | number | No       | 25      | Number of results per page.                       |
| **Page** (page)              | number | No       | 1       | Page number for pagination.                       |

Responses are cached with a TTL of 300 seconds (5 minutes). Requests have an 8-second timeout.

### Usage

To use this content source in a block:

1. In PageBuilder, add a feature block to your page that accepts a content source.
2. Select **schema-feed** as the content source.
3. Enter the **Schema Name** for the custom schema you want to query.
4. Optionally configure **Sort By**, **Query**, **Size**, and **Page** to control which documents are returned.

The content source returns a response where `data` is an array of documents:

```json
{
  "data": [
    {
      "schema_content": { /* your custom schema fields */ },
      "schema_name": "your-schema",
      "document_id": "ABC123...",
      "first_publish_date": "2026-04-07T21:20:09.484Z",
      "publish_date": "2026-04-08T21:28:38.677Z",
      "created_date": "2026-04-07T21:13:26.751Z"
    }
  ]
}
```

Each element has the same structure as the schema item response. The `schema_content` object contains your custom schema fields.

### Example feature block

The following skeleton shows a minimal feature block that renders a list of documents from the schema feed source. Use it as a starting point for building custom list or grid pages.

```jsx
import React from "react";
import PropTypes from "@arc-fusion/prop-types";
import { useContent } from "fusion:content";
import { useFusionContext } from "fusion:context";

const SchemaFeedFeature = ({ customFields }) => {
  const { arcSite } = useFusionContext();

  const content = useContent(
    customFields?.contentConfig
      ? {
          source: customFields.contentConfig.contentService,
          query: customFields.contentConfig.contentConfigValues,
        }
      : {},
  );

  const items = content?.data;

  if (!items || items.length === 0) return null;

  // Replace with your own schema fields and markup
  return (
    <section>
      {items.map((item) => {
        const { schema_content: schemaContent, document_id: docId } = item;

        return (
          <article key={docId}>
            <h2>{schemaContent.title}</h2>
            <p>{schemaContent.description}</p>
          </article>
        );
      })}
    </section>
  );
};

SchemaFeedFeature.propTypes = {
  customFields: PropTypes.shape({
    contentConfig: PropTypes.contentConfig().tag({
      group: "Configure Content",
      label: "Schema Feed Source",
    }),
  }),
};

SchemaFeedFeature.label = "Schema Feed Feature – Arc Block";

export default SchemaFeedFeature;
```

## Related resources

- [Introduction to Arc XP Blocks](https://dev.arcxp.com/themes/introduction-to-arc-blocks/)
- [How to customize a block](https://dev.arcxp.com/themes/how-to-guides/how-to-customize-a-block/)