#Field configuration
#Settings
Each field must have the following settings configured to be added to a model:
Property | Description |
---|---|
Display name | This is what is shown to content editors throughout the application |
API ID | This is what is exposed within the API as a field within your model. |
Description | Displays a hint for content editors and API users. |
Not all settings are available for all field types.
#Use as title field
You can set multiple fields as titles to appear within the relational picker instead of IDs. You cannot set a field as a title this when the field visibility is set to hidden, API only or read only.
UI | Management SDK |
---|---|
On the Settings tab, under Field options, select the Use as title field checkbox. | Add the isTitle:`true` parameter. Here's an example. |
Use as a title field
#Allow multiple values
You should select this if you wish to accept multiple values for the field. Setting multiple values for the field returns an array to the API.
- You can select this checkbox only during field creation, and it will be read-only after that.
- You cannot use the title field with this option.
UI | Management SDK |
---|---|
On the Settings tab, under Field options, select the Allow multiple values checkbox. | Add the isList:`true` parameter. Here's an example. |
Allow multiple values
#Localize field
Enabling this field allows translations per locale configured on your project.
You cannot use Set initial value with this option.
UI | Management SDK |
---|---|
On the Settings tab, under Field options, select the Localize field checkbox. | Add the isLocalized:`true` parameter. Here's an example. |
Localize field
#(Rich text fields only) Embed options
You can enable rich text embedding per field while adding or editing a Rich Text field. On the Settings tab, under Field options, select the Enable embedding checkbox, and then select the models that should be embedded in your Rich text field.
This setting is permanent and cannot be edited after the initial save.
Rich Text Options
#Validations
Not all validation options are available for all field types.
#Make field required
Marking a field as required prevents a content entry from being saved if the field is left empty. The API will mark this field as non-nullable.
You cannot mark a field as required when the field visibility is set to API only.
UI | Management SDK |
---|---|
On the Validations tab, select the Make field required checkbox. | Add the isRequired:`true` parameter. Here's an example. |
Note the following points:
- You can set hidden and read-only fields as required, but you cannot edit them in the content form. In this case, you need to provide a Migration value to avoid any errors when saving a content entry.
- You can modify this field after initial field creation. If you want to mark a field as required after you've created content entries based on the model, you need to provide a Migration value. This migration value is automatically updated in all content entries where you previously did not provide any value.
- After initial field creation, if you want to set a field as required and then unique, follow these steps:
- Select the Make field required checkbox, and provide a migration value.
- Go through every content entry for this model, and modify the value of the field so that it is unique across all entries.
- Republish all the content entries that you changed.
- Go back to the model, and select the Set field as unique checkbox.
Make field required
#Set field as unique
Enabling this ensures content cannot be saved if the same value exists within another entry for this field. Uniqueness is checked per Content stage.
UI | Management SDK |
---|---|
On the Validations tab, select the Set field as unique checkbox. | Add the isUnique:`true` parameter. Here's an example. |
Note the following points:
- You can modify this field after initial field creation.
- After field creation, if you want to set a field as unique and then required, follow these steps:
- First, ensure that all entries have a value set for the field and republish them.
- Then, select the Make field required checkbox.
Set field as unique
#Limit character count
This validation allows you to specify the minimum and maximum number of characters, and an optional custom error message if the requirements are not fulfilled.
UI | Management SDK |
---|---|
On the Validations tab, select the Limit character count checkbox, and then choose one of the following options:
| Add the validations object. Here's an example. |
Limit character count
#Match a specific pattern
This validation allows you to accept a specific regular expression. To set this up, follow these steps:
- On the Validations tab, select the Match a specific pattern checkbox.
- From the list, choose a pattern type, and provide a regular expression. You do not need to wrap the regular expression in opening or closing slashes.
- (Optional) Choose whether the matched pattern can be case insensitive, multiline, or single line.
- (Optional) Provide a custom error message if the regular expression does not match the specified pattern.
Match a specific pattern
#Common patterns
You can use an existing common pattern from the web app, or provide your own.
URL
^(http://www\.|https://www\.|http://|https://)?[a-z0-9]+([-\.]{1}[a-z0-9]+)*\.[a-z]{2,5}(:[0-9]{1,5})?(/.*)?$
Phone
^(?:(?:\(?(?:00|\+)([1-4]\d\d|[1-9]\d?)\)?)?[\-\.\ \\\/]?)?((?:\(?\d{1,}\)?[\-\.\ \\\/]?){0,})(?:[\-\.\ \\\/]?(?:#|ext\.?|extension|x)[\-\.\ \\\/]?(\d+))?$
[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?
Slug
^[a-z0-9]+(?:[-/][a-z0-9]+)*$
#Unicode characters
Hygraph field validations support unicode (non-latin) characters. You can add Unicode character classes - which typically correspond to specific alphabets - to a custom Regular Expression field validation. You can read about the syntax here.
#Restrict a specific pattern
This validation option allows you to not accept specific regular expression.
- On the Validations tab, select the Restrict a specific pattern checkbox.
- From the list, choose a pattern type, and provide a regular expression. You do not need to wrap the regular expression in opening or closing slashes.
- (Optional) Choose whether the matched pattern can be case insensitive, multiline, or single line.
- (Optional) Provide a custom error message if the regular expression does not match the specified pattern.
Restrict a specific pattern
#Advanced
Not all advanced settings are available for all field types.
#Set initial value
You can define an initial value for content editors. This doesn't have any effect on the API when performing mutations.
UI | Management SDK |
---|---|
On the Advanced tab, select the Set initial value checkbox, and add the value there. | To set the initial value for a field, use the initialValue parameter to pass a value. Here's an example. |
Set initial value
#Conditional visibility
With conditional visibility, you can show selected fields to editors only when they need them. You can still query the values of hidden fields, as conditional visibility only affects the ability to see a field in the UI. For more information on conditional visibility, see our docs here.
Conditional visibility inside field details
#Field visibility
Field visibility has no relation with permissions or security.
UI | Management SDK |
---|---|
On the Advanced tab, use the Field visibility dropdown to select an option. | To indicate field visibility, use the visibility parameter to pass a type. Here's an example. |
The following options are available in the UI:
- Read / Write - The field will be accessible for read/write operations. Default.
- Read only - The field will be shown, but cannot be edited in the UI. You can update via the API if required.
- Hidden - The field will not be shown in the UI, but can be referenced by other fields such as Slugs.
- API only - Field is not shown in the UI, but can be used via the API using mutations.
You can set field visibility by passing one of the following types in the Management SDK:
visibility: "READ_WRITE"
visibility: "READ_ONLY"
visibility: "HIDDEN"
visibility: "API_ONLY"
Field visibility