Choose your language:
    Create a new field

    When creating a field you can also set validators and presentation option.

    Check the example below for all the options you can use: Create a field with validators and presentation options.

    Following you can find another example about how you can create a modular content field: Add modular content with blocks

    Parameters
    label  string  Required

    The label of the field

    fieldType  string  Required

    Type of input

    apiKey  string  Required

    Field API key

    localized  boolean  Optional

    Whether the field needs to be multilanguage or not

    validators  object  Optional

    Optional field validations

    appearance  object  Optional

    Field appearance details, plugin configuration and field add-ons

    position  integer  Optional

    Ordering index

    hint  string, null  Optional

    Field hint

    defaultValue  boolean, null, string, number, object  Optional

    Default value for Field. When field is localized accepts an object of default values with site locales as keys

    Deprecated
    appeareance  object  Deprecated  Optional

    Field appearance

    This field contains a typo and will be removed in future versions: use appearance instead

    Returns
    Returns a field object.

    Examples

    Create a field with validators and presentation options

    When creating a new field you can specify the plugins and validations that the field should have.

    Depending on the field type you have different options, for the editor form and for the validations that you can apply. Following you'll find a summary of all the types with their options.

    boolean - Boolean

    • editor: boolean
    • parameters: {}
    • validators: {}

    color - Color picker

    • editor: color_picker
    • parameters:
      • enableAlpha: false Let editors control the alpha channel.
      • presetColors: [] Array of hex codes. This is useful if you want to present your editors a set of reference colors. Delimit colors with a comma.
    • validators:
      • required: {} make field required.

    date_time - Date time

    • editor: date_time_picker
    • parameters: {}
    • validators:
      • required: {} make field required.
      • dateTimeRange: you should provide an object with two optional attributes: min or max with which you can define ranges. The datetime format is ISO-8601.

    date - Date

    • editor: date_picker
    • parameters: {}
    • validators:
      • required: {} make field required.
      • dateRange: you should provide an object with two optional attributes: min or max with which you can define ranges. The date format is ISO-8601.

    file - Asset upload

    • editor: file
    • parameters: {}
    • validators:
      • required: {} make field required.
      • fileSize: an object with minValue, maxValue and minUnit, maxUnit. The units can be B, KB or MB. You can express only minimum values, only maximum values or both.
      • imageDimensions: an object with heightMaxValue, heightMinValue, widthMaxValue widthMinValue expressed in pixels. You can express only minimum values, only maximum values or both.
      • extension: either an object with predefinedList: image or video or document. Otherwise it should be an array of extensions allowed.
      • requiredAltTitle: an object with alt and title attributes that can have true or false values.

    float - Float number

    • editor: float
    • parameters: {}
    • validators:
      • required: {} make field required.
      • numberRange: an object with min and max attributes that you can use to specify a range.

    gallery - Gallery of assets

    • editor: gallery
    • parameters: {}
    • validators:
      • required: {} make field required.
      • fileSize: an object with minValue, maxValue and minUnit, maxUnit. The units can be B, KB or MB. You can express only minimum values, only maximum values or both.
      • imageDimensions: an object with heightMaxValue, heightMinValue, widthMaxValue widthMinValue expressed in pixels. You can express only minimum values, only maximum values or both.
      • extension: either an object with predefinedList: image or video or document. Otherwise it should be an array of extensions allowed.
      • requiredAltTitle: an object with alt and title attributes that can have true or false values.

    integer - Integer number

    • editor: integer
    • parameters: {}
    • validators:
      • required: {} make field required.
      • numberRange: an object with min and max attributes that you can use to specify a range.

    json - JSON

    • editor: json
    • parameters: {}
    • validators:
      • required: {} make field required.

    lat_lon - Latitude and longitude

    • editor: map
    • parameters: {}
    • validators:
      • required: {} make field required.

    link - Link to a record

    • editor: link_select or link_embed
    • parameters: {}
    • validators:
      • required: {} make field required.
      • itemItemType: an object with the attribute itemTypes which as a value has an array of allowed model ids. This validator is required.
      • unique: {} don't allow duplicate links.

    links - Set of links to records

    • editor: link_select or link_embed
    • parameters: {}
    • validators:
      • required: {} make field required.
      • itemsItemType: an object with the attribute itemTypes which as a value has an array of allowed model ids. This validator is required.

    rich_text - Modular content

    • editor: rich_text
    • parameters: the option startCollapsed: true makes the modular blocks collapsed by default.
    • validators:
      • richTextBlocks: an object with the property itemTypes which is an array that specifies all the modular blocks ids (model ids) that are part of the modular content. To pick the modular blocks you should create first the models with the modularBlock property set to true.
      • size: an object with min, max, multipleOf to specify a validator on the number of blocks in the modular content.

    seo - SEO

    • editor: seo
    • parameters: {}
    • validators:
      • requiredSeoFields: is an object where you can specify which SEO sub-fields are required. You should pass description, image, title, twitterCard as true or false.
      • fileSize: an object with minValue, maxValue and minUnit, maxUnit. The units can be B, KB or MB. You can express only minimum values, only maximum values or both.
      • imageDimensions: an object with heightMaxValue, heightMinValue, widthMaxValue widthMinValue expressed in pixels. You can express only minimum values, only maximum values or both.

    slug - Slug

    • editor: slug
    • parameters: as parameter you can pass urlPrefix. A prefix that will be shown in the editor's form to give some context to your editors.
    • validators:
      • slugTitleField: is an object with titleFieldId in which you need to specify which field is going to be the reference for automatically generating the slug.
      • required: {} make field required.
      • length: an object in which you can specify min and max number of characters. Used together you can specify a range.

    string - Single-line text

    • editor: single_line
    • parameters: heading can be true or false and indicates if the field should be shown bigger, as a field representing a heading.
    • validators:
      • required: {} make field required.
      • unique: {} don't allow duplicate strings.
      • length: an object in which you can specify min and max number of characters. Used together you can specify a range.
      • format: specify a pattern that should be matched. It can be a predefinedPattern which can be email or url, otherwise you can specify a customPattern which is a regular expression that needs to be matched.
      • enum: an object with a values property in which you can specify an array of possible strings. These will be the only options that your editor will be able to pick with a dropdown select.

    text - Multi-line text

    • editor: markdown, wysiwyg, or textarea
    • parameters: both markdown and wysiwyg editors accept a toolbar parameter. In this parameter you can specify the set of toolbar buttons that will be shown in the editor. The full set for the markdown editor is: ['heading', 'bold', 'italic', 'strikethrough', 'unordered_list', 'ordered_list', 'quote', 'link', 'image', 'fullscreen'] while the full set for the wysiwyg editor is ['format', 'bold', 'italic', 'strikethrough', 'ordered_list', 'unordered_list', 'quote', 'table', 'link', 'image', 'show_source', 'undo', 'redo', 'align_left', 'align_center', 'align_right', 'align_justify', 'outdent', 'indent', 'fullscreen'].
    • validators:
      • required: {} make field required.
      • length: an object in which you can specify min and max number of characters. Used together you can specify a range.
      • format: specify a pattern that should be matched. It can be a predefinedPattern which can be email or url, otherwise you can specify a customPattern which is a regular expression that needs to be matched.

    video - External video

    • editor: video
    • parameters: {}
    • validators:
      • required: {} make field required.
    Example code:
    const SiteClient = require('datocms-client').SiteClient;
    const client = new SiteClient('YOUR-API-TOKEN');
    const itemTypeId = '124';
    client.fields.create(itemTypeId, {
    label: 'Title',
    fieldType: 'string',
    apiKey: 'title',
    localized: true,
    validators: {
    required: {}
    },
    appearance: {
    editor: 'single_line',
    parameters: {
    heading: false
    },
    addons: [
    {
    id: '1234',
    parameters: {}
    }
    ]
    },
    position: 1,
    hint: 'This field will be used as post title',
    defaultValue: {
    en: 'A default value',
    it: 'Un valore di default'
    }
    })
    .then((field) => {
    console.log(field);
    })
    .catch((error) => {
    console.error(error);
    });
    Returned output:
    > node example.js
    {
    "id": "124",
    "label": "Title",
    "fieldType": "string",
    "localized": true,
    "defaultValue": {
    "en": "A default value",
    "it": "Un valore di default"
    },
    "apiKey": "title",
    "hint": "This field will be used as post title",
    "validators": {
    "required": {}
    },
    "appearance": {
    "editor": "single_line",
    "parameters": {
    "heading": false
    },
    "addons": [
    {
    "id": "1234",
    "parameters": {}
    }
    ]
    },
    "position": 1,
    "itemType": "44"
    }
    Add modular content with blocks

    To create a modular content field with some blocks, you first need to create the modular blocks. For DatoCMS a modular block is just like another model, so we'll create first a couple blocks and then add them to our modular content field.

    Example code:
    const { SiteClient } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    async function createModularContent() {
    const modularBlock1 = await client.itemTypes.create({
    name: "Modular Block 1",
    apiKey: "modular_block1",
    modularBlock: true,
    });
    const modularBlock2 = await client.itemTypes.create({
    name: "Modular Block 2",
    apiKey: "modular_block2",
    modularBlock: true,
    });
    const itemTypeId = "1234";
    const field = await client.fields.create(itemTypeId, {
    label: "Modular content",
    fieldType: "rich_text",
    apiKey: "modular_content",
    validators: {
    richTextBlocks: {
    itemTypes: [modularBlock1.id, modularBlock2.id],
    },
    },
    });
    console.log(field);
    }
    createModularContent();
    Returned output:
    { id: '1033076',
    label: 'Modular content',
    localized: false,
    hint: null,
    validators: { richTextBlocks: { itemTypes: [Array] } },
    appeareance:
    { editor: 'rich_text',
    parameters: { startCollapsed: false },
    addons: [] },
    appearance:
    { editor: 'rich_text',
    parameters: { startCollapsed: false },
    addons: [] },
    position: 4 }