microCMS
Documentation
  • Pricing
  • Blog
  • FAQ
  • Contact
  • Sign In
  • Get started for free
Navigation
Tutorial
Next.js
  • Integration with Next.js
  • Getting Started with App Router
  • Tutorial (App Router)
  • Getting Started with Pages Router
  • Tutorial (Pages Router)
Astro
  • Getting Started
  • Integration with Astro
  • Tutorial
Nuxt
  • Integration with Nuxt
  • Getting Started
  • Tutorial
Gatsby
  • Integration with Gatsby
  • Getting Started
  • Tutorial
JavaScript
  • Integration with JavaScript
  • Getting Started (Browser)
  • Getting Started (Server)
PHP
  • Integration with PHP
  • Getting Started
Ruby
  • Integration with Ruby
  • Getting Started
Go
  • Integration with Go
  • Getting Started with microCMS
Manual
  • Introduction
Account & Login
  • Account Registration
  • Login
  • Email Address Authentication
Services
  • Creating a Service
  • Service Configuration
  • Template
  • Service Deletion
Payment
  • Change of Pricing Plan
  • Registering and Changing Payment Methods
API
  • Creating and Managing APIs
  • API Settings
  • Export/Import of API Schema
Fields
  • Text Field
  • Text Area
  • Image
  • Multiple Images
  • Date
  • Boolean
  • Selectable Field
  • Content Reference
  • Multiple Content References
  • Number
  • File
  • Extended Field
  • Repetition
  • Custom
Contents
  • CSV Export of Content
  • Content Creation
  • Content Editing
  • Content Management
  • View
  • Content Status
  • Custom Status
  • Setting the Content ID
  • Automatically Assigned Values for Content
  • CSV Import of Content
  • API Preview
  • Examples of Using Query Parameters with API Preview
  • Integration Methods by Rendering Type
  • Screen Preview
  • Setting Up Webhooks for Content
Rich Editor
  • How to Use the Rich Editor
  • Rich Editor WRITE API
  • How to Use the Old Rich Editor
Reviews
  • Review
  • AI Review
Media
  • Media Management
  • Changing Media Filters and Display Order
  • Media Tag Configuration
  • Setting Up Media Webhooks
  • Custom Domain Settings for Media
Permission Management
  • Member Management
  • Roles (Permission Management in the Admin Panel)
Environments
  • Multiple Environments (Development Environment)
  • Merging API Settings Between Environments
Connection
  • Amazon S3 Integration
Logs
  • Audit Log
  • Data Transfer Volume
Security
  • Content Update History
  • IP Restrictions for Management Dashboard
  • IP Restrictions for APIs
Authentication
  • Setting Up Two-Factor Authentication
  • Mandatory Two-Factor Authentication
  • Single Sign-On
Specifications & Limitations
  • Recommended Environment
  • Limitations / Precautions
Content API
  • What is the Content API?
Basic Operations
  • GET /api/v1/{endpoint}
  • GET /api/v1/{endpoint}/{content_id}
  • POST /api/v1/{endpoint}
  • PUT /api/v1/{endpoint}/{content_id}
  • PATCH /api/v1/{endpoint}/{content_id}
  • DELETE /api/v1/{endpoint}/{content_id}
API Keys
  • API Key (API Authentication and Authorization Management)
  • Migration from the Old API (X-API-KEY, etc.)
Responses & Error Handling
  • Response format for each field in the GET API
  • Specifying Query Parameters in the GET API
  • Error Responses of the Content API
Management API (Beta)
  • POST /api/v1/roles
  • DELETE /api/v1/roles/{role_id}
  • GET /api/v1/roles/{role_id}
  • PATCH /api/v1/roles/{role_id}
  • GET /api/v1/roles
  • What is the Management API?
Content Operations
  • PUT /api/v1/contents/{endpoint}/{content_id}/reservation
  • GET /api/v1/contents/{endpoint}
  • GET /api/v1/contents/{endpoint}/{content_id}
  • PATCH /api/v1/contents/{endpoint}/{content_id}/status
  • PATCH /api/v1/contents/{endpoint}/{content_id}/createdBy
Media Operations
  • GET /api/v2/media
  • GET /api/v1/media
  • POST /api/v1/media
  • DELETE /api/v2/media
Member Operations
  • PATCH /api/v1/members/{member_id}
  • GET /api/v1/members
  • GET /api/v1/members/{member_id}
API Operations
  • POST /api/v1/apis
  • GET /api/v1/apis
  • GET /api/v1/apis/{endpoint}
Service Operations
  • GET /api/v1/service
Responses & Error Handling
  • Management API Error Responses
Image API
  • What is the Image API?
Parameters
  • Image Size
  • Quality
  • Resolution and Screen Size
  • Format
  • Text
  • Border
  • Padding
  • Shape
  • Download
  • Watermark
MCP Server
  • microCMS MCP
  • microCMS Document MCP Server
  • Top
  • Manual

Extended Field

Last updated: 2026/07/14

By using the extended fields, you can select external data within the management screen.

By loading applications developed independently as extended fields, it becomes possible to achieve flexible data management that is not available with the default fields.

Actual Usage Image

Below is a demo of an extended field that reads and selects external member information.

【活用事例】メンバー一覧から特定のメンバーを選択する拡張フィールド | microCMSブログ
https://blog.microcms.io/member-select-expansion-field

Please refer to the following document for submission using the API and CSV.

POST /api/v1/{endpoint}
https://document.microcms.io/en/content-api/post-content#hb1d419d743
CSV Import of Content
https://document.microcms.io/en/manual/csv-import#h2b3036ae9c

Usage Examples

For other examples of using extended fields, please refer to the cases introduced on our blog below.

ハイライトや自動補完が可能なHTML編集用の拡張フィールドを公開しました | microCMSブログ
https://blog.microcms.io/html-field/
拡張フィールド(iframe連携)でGoogle Mapsと連携し、「地図フィールド」を実現する | microCMSブログ
https://blog.microcms.io/iframe-filed-with-google-maps/
microCMSの拡張フィールドで生成AIと連携し、ブログ記事のディスクリプションを自動作成する | microCMSブログ
https://blog.microcms.io/generate-description-with-ai/

Embedded Image

The extended field utilizes an iframe as its internal mechanism. Below, we will introduce the detailed technical specifications and implementation methods.

Specifications

In the extended field, the window.postMessage API is used to exchange values between the iframe and the microCMS management screen.


Communication Specifications from microCMS to iframe

① Obtaining Initial Values

First, when you open the content creation/editing screen where the extended field is set, the microCMS management screen sends a postMessage to the iframe as follows.

{
  id: 'some-id',  // iframe identifier
  action: 'MICROCMS_GET_DEFAULT_DATA',
  message: {
    data: 'Registering data in the iframe' // Actual data for the extended field
  },
  user: {
    email: 'example@microcms.co.jp' // Logged-in user's email address
  },
  context: {
    type: 'new_content', // 'new_content' for new content creation, 'edit_content' for editing
    endpoint: 'some-api', // Content API endpoint name
    content: {
      id: null // null for new content creation, actual content ID for editing
    }
  }
}


The iframe side can receive the above message by setting an EventListener for the message event.
id should be stored somewhere as it will be used during transmission.
message value will be used as the initial value. (Initially, it is undefined)
user.email contains the logged-in user's email address.

window.addEventListener('message', (e) => {
  if (
    e.isTrusted === true &&
    e.data.action === 'MICROCMS_GET_DEFAULT_DATA'
  ) {
    // Save id and message
    // e.data.id: Identifier
    // e.data.message: Configured value
    // e.data.user.email: Logged-in user's email address information
    // e.data.context.endpoint: API endpoint name
  }
});


Communication Specifications from iframe to microCMS

② Sending Data

Conversely, if you want to POST some data from the iframe to the microCMS management screen, you can do so by sending a postMessage as follows.

window.parent.postMessage(
  {
    id: 'some-id',  // iframe identifier
    action: 'MICROCMS_POST_DATA',
    message: {
      id: 'some-id',
      title: 'some-title',
      description: 'some-description',
      imageUrl: 'some-image-url',
      updatedAt: 'some-updated-at',
      data: {    // Part that will be the API response
        id: '123'
      }
    }
  },
  'https://your-service-id.microcms.io'
);


id should be specified as the id received from microCMS during screen loading.
action should be specified as 'MICROCMS_POST_DATA'.
message contains the following metadata items.

  • id (String)
  • title (String)
  • description (String)
  • imageUrl (String: URL format)
  • updatedAt (Date)


All of these are optional items and are values set for easier management within the microCMS management screen.
If set, they will be displayed in the content list screen, etc.

Additionally, there is a data field for the API response.

  • data (Type varies)


The value specified in data will be returned as the value for the iframe field from the content GET API.

To ensure secure communication, specify the URL of the microCMS management screen as the second argument of postMessage.

② Response

While there is no response for postMessage, a pseudo-response is returned to indicate whether the data change was successful.
Upon success, you can receive a postMessage like the following.

{
  id: 'some-id',  // iframe identifier
  action: 'MICROCMS_POST_DATA_SUCCESS',
  message: value  // Sent value
}


In case of failure, a postMessage like the following will be returned.

{
  id: 'some-id',  // iframe identifier
  action: 'MICROCMS_POST_DATA_FAILURE',
  error: 'Error message'
}


③ Changing Styles

The height of the iframe is determined at the initial load, so it may become difficult to see when the UI inside the iframe changes.
Therefore, by sending a postMessage as follows from the iframe, you can change the height and width of the iframe itself.

window.parent.postMessage(
  {
    id: this.id,
    action: 'MICROCMS_UPDATE_STYLE',
    message: {
      height: 300,
      width: '100%'
    }
  },
  'https://your-service-id.microcms.io'
);


API Response

④ Obtaining Responses

Here is an example of an API schema.



Set the following value as data in the iframe field.

{
    data: {
        id: '123'
    }
}


The entered value can be obtained from the content GET API as follows.

{
    "id": "mir1wo77g",
    "createdAt": "2020-07-21T14:12:14.606Z",
    "updatedAt": "2020-07-21T14:12:14.606Z",
    "publishedAt": "2020-07-21T14:12:14.606Z",
    "title": "Title Test",
    "iframe": {
        "id": "123"
    }
}

How to Specify Queries for Content API

The area returned as a response (data) currently cannot utilize queries.

However, the metadata area (id,title,description,imageUrl,updatedAt) can utilize queries.

Applicable Queries

  • orders
  • filters
  • q (id,title,description,imageUrl are searchable.)

The conditions that can be applied for the filters query parameter vary depending on the type of metadata. For details, please refer to the Specification of Query Parameters in GET API.

How to Specify Fields

  • {field_name}.id 
  • {field_name}.title
  • {field_name}.description
  • {field_name}.imageUrl
  • {field_name}.updatedAt

Query Examples

  • ?orders={field_name}.id
  • ?filters={field_name}.id[equals]some-id
  • ?filters={field_name}.title[contains]some-title
  • ?q=string to search

How to Configure in the microCMS Management Screen

Select "Extended Field" from the API settings > API Schema Type.



Enter the URL you want to load in the extended field. localhost can also be specified.



The field configuration is now complete.
When you navigate to the content editing screen, the URL you specified earlier will be displayed via an iframe.

API Detailed Settings

In the detailed settings for extended fields, the following items can be configured.

Setting Item

Description

Required Field

When enabled, input is required during submission.

Description Text

This is the description text displayed on the submission screen.

Extended Field URL

Enter the URL to load.

Information

Regarding the mandatory field check for the input content of the extended fields, the input content varies depending on the application being loaded, so it is designed in such a way that checks cannot be performed based on the same criteria as normal fields.
(Specifically, once data is sent from the iframe side, it is recognized as filled in thereafter.)

If strict checks are required, we kindly ask that you implement validation checks on the application side that is being loaded.

microcms-field-extension(SDK)

This is an SDK that allows you to implement extended fields without worrying about the specifications of iframes.
The microcms-field-extension at the following URL is a repository that manages multiple libraries.
We provide various libraries and templates.

GitHub - microcmsio/microcms-field-extension: Libraries for create field extension
https://github.com/microcmsio/microcms-field-extension
Information

microcms-field-extension is recommended for new use and follows a maintenance policy of continuous feature improvement and support (Active). For the maintenance policy of the SDK, please refer to the "SDK Maintenance Policy" page in the "Limitations / Notes" section.

microcms-field-extension-api

This is a framework-agnostic library. It can be used with JavaScript, TypeScript, and various frameworks such as Vue.js.

microcms-field-extension/packages/api at main · microcmsio/microcms-field-extension
https://github.com/microcmsio/microcms-field-extension/tree/main/packages/api

microcms-field-extension-react

This is a React Hooks-based library that wraps microcms-field-extension-api. It is convenient to use when working with React.

microcms-field-extension/packages/react at main · microcmsio/microcms-field-extension
https://github.com/microcmsio/microcms-field-extension/tree/main/packages/react

Various Templates and Examples

There are templates available for create-react-app and Next.js, among others. You can easily set up the implementation environment for extended fields by running commands with npx.
For example, you can set up the environment for Next.js by simply executing the following command.

npx create-next-app my-app --example https://github.com/microcmsio/microcms-field-extension-sdk/tree/main/examples/nextjs
cd my-app
export NEXT_PUBLIC_MICROCMS_ORIGIN='https://example.microcms.io'
npm run dev

Additionally, more examples are planned to be added.

microcms-field-extension/examples at main · microcmsio/microcms-field-extension
https://github.com/microcmsio/microcms-field-extension/tree/main/examples

Contents

  • Actual Usage Image
  • Usage Examples
  • Embedded Image
  • Specifications
  • Communication Specifications from microCMS to iframe
  • Communication Specifications from iframe to microCMS
  • API Response
  • How to Specify Queries for Content API
  • How to Configure in the microCMS Management Screen
  • API Detailed Settings
  • microcms-field-extension(SDK)
  • microcms-field-extension-api
  • microcms-field-extension-react
  • Various Templates and Examples
  • Company
  • Legal Notice
  • Terms of Service
  • Privacy Policy

Copyright © microcms.io All rights reserved.