---
title: Content types
related:
- https://docs.kentico.com/documentation/developers-and-admins/development/content-types/reusable-field-schemas.md
- https://docs.kentico.com/documentation/developers-and-admins/development/content-types/limit-the-pages-users-can-create.md
- https://docs.kentico.com/documentation/developers-and-admins/api/management-api.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
A content type is a template that defines the data structure, functionality, and behavior for all content items that are based on it. When creating content types, you determine their:
- Target usage ([reusable content](https://docs.kentico.com/documentation/business-users/content-hub.md), [pages](https://docs.kentico.com/documentation/business-users/website-content.md), [emails](https://docs.kentico.com/documentation/business-users/digital-marketing/emails.md), [headless items](https://docs.kentico.com/documentation/business-users/headless-content.md))
- Fields (define the content model and data structure)
- Editing form layout (the interface through which users create and modify the content items)
> **Tip:** **AI-assisted content modeling**
>
> Use [KentiCopilot](https://docs.kentico.com/guides/development/kenticopilot.md) to prototype and validate your content model with AI. See [Prototype your model with Content modeling MCP server](https://docs.kentico.com/guides/development/kenticopilot/build-content-model-with-mcp.md) and [Content Modeling MCP server](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-mcp.md). For retrieval and management of content types, see [Management MCP server](https://docs.kentico.com/documentation/developers-and-admins/api/management-api.md).
>
> If you are starting from an existing design, the `design-to-content` skill in the [web development plugin](https://github.com/Kentico/xperience-by-kentico-kenticopilot/tree/main/plugins/kentico-web-development) derives a whole model from a design, wireframe, or Figma file, including the [reusable field schemas](https://docs.kentico.com/documentation/developers-and-admins/development/content-types/reusable-field-schemas.md), [taxonomies](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md), and content relationships the design implies.
## Create content types
To create a new content type:
1. Open the **Content types** application.
2. Select **New content type**.
3. Fill in the following values:
- **Content type name** – the name that is displayed to users in the administration interface.
- **Code name**
- **Namespace** – the namespace is a prefix that distinguishes between content types. For example, it can be used to separate content types created for different sites, identify content types imported as part of third-party modules, etc.
- **Name** – a unique content type identifier, which is appended to the namespace.
> **Note:** **Important**
>
> When creating content types, _**never**_ use names beginning with an _**underscore**_ ('_\__') character (e.g., '_\_article_') to avoid conflicts with system fields.
>
> Always use a _**unique namespace**_. Never use the **cms**, **om**, **content** or **ContentItemData** prefixes. A recommended option is to use your company name or an abbreviation as the prefix. For example: _ACME_
- **Icon** – an icon identifying the content type when creating items (pages, emails, etc.).
- **Use for** – determines the target usage for the content type.
- _Reusable content_ – intended for reuse across multiple channels and channel types.
- _Pages_ – used for [website channels](https://docs.kentico.com/documentation/developers-and-admins/configuration/website-channel-management.md).
- _Emails_ – used for [email](https://docs.kentico.com/documentation/business-users/digital-marketing/emails.md) content.
- _Headless items_ – used for [headless channels](https://docs.kentico.com/documentation/developers-and-admins/configuration/headless-channel-management.md).
- **Short code name** – automatically generated based on the full _Code name_. Serves as a unique identifier of the content type in scenarios and environments where special characters (underscores and periods) are not supported, for example when generating type and field names in the [GraphQL schema of headless channels](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-headless-content.md). If you encounter a name conflict in these scenarios, you can edit the short code name value on the _General_ tab of existing content types.
4. **Save** the content type.
The system creates the content type and opens its configuration menu.
## Configure created content types
When configuring content types, you determine their functionality and purpose.
You can:
- [Add fields](#add-fields) to a content type.
- [Allow editors to link other content items](#add-the-option-to-link-content-items).
- [Allow editors to upload files](#add-option-to-upload-files) to content items.
- [Configure mass asset upload](#mass-asset-upload-configuration) for a content type.
- [Allow editor to tag content](#add-option-to-tag-content).
### Add fields
Content type fields are used to store structured data. Each field corresponds to a database column and is of a certain [data type](https://docs.kentico.com/documentation/developers-and-admins/customization/field-editor/data-types.md). Developers access the content of fields from the code to format and display stored data.
> **Note:** Fields that use custom data types are not supported by the GraphQL API for [headless channels](https://docs.kentico.com/documentation/developers-and-admins/configuration/headless-channel-management.md) and their values cannot be retrieved. Only built-in scalar types are available in content types exposed through the API. See [Retrieve headless content](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-headless-content.md) to learn more about what is included in the GraphQL schema.
You can create content type fields via the [field editor](https://docs.kentico.com/documentation/developers-and-admins/customization/field-editor.md) on the **Fields** tab when editing a content type in the **Content types** application:
1. Select **New field**.
2. Define a custom field using the field editor.
- There are a couple of things to keep in mind when naming fields – see [Field naming guidelines](#field-naming-guidelines) for more information.
3. **Save** the field.
4. Repeat the above steps to create all desired fields.
Content items based on this content type now allow editors to input data into the added fields.
#### Field naming guidelines
Since each field is represented as a database column and potentially a C# class, adhere to the following restrictions when naming fields:
- Don't use the same name for fields across different content types in the system.
- When adding fields, include a prefix based on the content type’s name in the field name, for example, _BenefitDescription_, _ArticleName_, or _ProductTitle_. Unique names like this help developers in various scenarios. For instance, in SQL JOINs, you won’t need aliases to identify columns from two or more tables, such as News _Title_ and Product _Title_.
- Don't use [C# keywords](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/) or [SQL keywords](https://en.wikipedia.org/wiki/List_of_SQL_reserved_words).
- Don't use the names _SystemFields_ and _Asset_ (these are used internally by the system).
> **Note:** If you migrate content types from an older Kentico version and the migrated content types contain fields with restricted names (for example, _Asset_), rename these fields after migration to ensure full compatibility with Xperience by Kentico.
Not following these recommendations can result in unexpected behavior, runtime errors, or uncompilable code.
### Add the option to link content items
You can enable users to link content items from other reusable content items.
1. In the **Content types** application, select the content type where you want to add the possibility to add linked content items.
2. Create a **New field**.
3. In **Data type**, select **Pages and reusable content** and fill in the required settings.
4. In **Form component**, select the **Combined content selector**.
5. In **Display items based on**, select whether you want to display items available in the selector based on **Content types** or a **Reusable field schema**.
6. Add content types that are allowed to be linked via **Allowed content types** or select a **Allowed reusable field schema**.
7. **Save** the field.
Now, whenever users edit a content item based on the content type, they can [link content items](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md#link-content-items) of allowed content types. You can then [retrieve](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-content-items.md#retrieve-linked-content-items) and use the linked items in your application's code.
> **Note:** **Linked item limitations for emails**
>
> Linked content items may have their own fields that link to further content items.
>
> When modeling the fields of content types for [emails](https://docs.kentico.com/documentation/business-users/digital-marketing/emails.md), the system has a **limit of 5 nested content item levels**. Further levels of linked items will not be loaded into the final email content.
### Add option to upload files
You can enable users to upload binary files to content items of a certain content type to create [content item assets](https://docs.kentico.com/documentation/glossary.md#content-management). You can also [configure](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-hub-configuration.md#customize-maximum-file-upload-size-and-chunk-size) the parameters of the file upload (e.g., maximum file size).
1. In the **Content types** application, select the **reusable content type** where you want to add the possibility to upload files.
2. Create a **New field**.
3. In **Data type**, select **Content item asset** and fill in the required settings.
4. In **Form component**, select the **Asset uploader**.
5. Configure **Allowed extensions**.
6. **Save** the field.
Now, whenever users edit a content item based on the content type, they can [upload binary files](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md) to the item to create a content item asset. You can then [retrieve](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-content-items.md#retrieve-assets) and use the assets in your application's code.
#### Mass asset upload configuration
You can allow users to upload multiple files in a single bulk into the Content hub, combined content selector, or rich text editor, and automatically convert them to content item assets of a specific content type. The system only supports converting all mass-uploaded files to a single content type.
1. In the **Content types** application, open the **Asset configurations -> Mass asset upload** tab.
2. Select the **Content type for mass-uploaded items**. You can select only a content type used for reusable content that has at least one content item asset field configured.
3. Select the **Content item asset field** of the content type which will store the uploaded file.
4. **Save** the settings.
Users can now [mass upload assets](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md#mass-asset-upload) into the Content hub, combined content selector, and [rich text editor](https://docs.kentico.com/documentation/business-users/rich-text-editor.md).
### Add option to tag content
You can enable content editors to add [tags](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md) to pages and reusable content items.
1. In the **Content types** application, select a content type for which you want to enable the option to tag content.
2. Create a **New field**.
3. In **Data type**, select **Taxonomy** and fill the required settings.
4. In **Form component**, select **Tag selector**.
5. In **Taxonomy group**, select from which [taxonomy](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md) users can select tags in this field.
6. **Save** the field.
Now, whenever you edit a content item based on the content type, you are able to add tags to the content.
> **Tip:** **Tip**: You can add multiple taxonomy fields to a single content type, each with a different set of tags.
### Add AIRA features
You can enable [AIRA features](https://docs.kentico.com/documentation/business-users/aira.md) for eligible fields to simplify editors' work when creating content. See [AIRA configuration](https://docs.kentico.com/documentation/developers-and-admins/configuration/aira-configuration.md#add-aira-features-to-your-content-types) for more information.
## Configure asset content types
### Automatically optimize image assets
To ensure that your content editors work with images that are properly optimized for use across different channels, you can configure the system to automatically convert all newly created images to a single image format, and optimize their file size by adjusting image quality or image dimensions. While the system retains the original version of the image in case of a future re-optimization, the original version is not accessible from the administration interface.
1. In the **Content types** application, select the content type for which you want to enable automatic image optimization.
2. In the **Content item asset** field, select **Enable automatic image format conversion**.
3. Select **Image extensions to convert**. You can choose only [optimizable image types](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-hub-configuration.md#customize-supported-file-types) that are [allowed](#add-option-to-upload-files) for the particular content type.
4. Select a single **Output image extension** for the converted images. If you are not sure which image format to use for the content item asset, see the [Image file type and format](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types) guide.
5. Select the **Quality** level of the converted images.
- Quality selection is unavailable for image formats that use lossless image compression, like _PNG_.
- While higher quality retains more image details, lowering the quality reduces the output file size.
6. _(Optional)_ In the **Image width limit** and **Image height limit** fields, you can set the maximum dimensions of the converted image. Images exceeding the set width or height limit are automatically resized to fit upon upload.
> **Note:** Setting a very low image width or height limit can result in poor-quality [image variants](#configure-image-variants) , as they will be generated from the downsized version of the original image. Make sure the limit is high enough to maintain visual quality across all variants.
7. **Save** the field.
Upon upload, images with the selected **Image extensions to convert** are automatically converted to images with the **Output image extension** in the specified **Quality**. Images with other extensions are uploaded without any optimization.
> **Tip:** We recommend [manually optimizing](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md#optimize-image-assets) several sample images before enabling automatic optimization to fine-tune the optimization parameters for the best results.
>
> If you notice undesired [compression artifacts](https://en.wikipedia.org/wiki/Compression_artifact) in the converted images, try increasing the quality until the artifacts are no longer visible.
### Configure image variants
Image variants are cropped and resized versions of an image, each defined by a specific aspect ratio and pixel dimensions. Variants allow marketers to control how images appear across different contexts, such as hero banners, social media posts, or thumbnails, and help developers address the [art direction](https://developer.mozilla.org/en-US/docs/Web/HTML/Responsive_images#art_direction) and [resolution switching](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images#how_do_you_create_responsive_images) problem.
Image variants are generated from the primary [optimized image](#automatically-optimize-image-assets), taking into account its format and quality. The [usage](#use-image-variants) of image variants is currently supported only for [website channels](https://docs.kentico.com/documentation/business-users/website-content.md).
You can add two types of image variant definitions:
- **Scaled variant** – Image dimensions are resized based on input while maintaining the original aspect ratio. If one dimension is set to 0, the system automatically calculates that dimension proportionally to preserve the aspect ratio. For example:
- If you define a variant with the size of **0 px × 200 px** and upload an image with the dimensions **600 px × 400 px**, the resulting image will have the dimensions **300 px × 200 px**, with the width calculated automatically to preserve the aspect ratio.
- If you define a variant with the size of **1000 px × 100 px** and upload an image with the dimensions **500 px × 500 px**, the resulting image will have the dimensions **100 px × 100 px**, proportionally downscaled so that neither dimension exceeds the defined limits.
- If you define a variant with the size of **1000 px × 800 px** and upload an image with the dimensions **500 px × 500 px**, the resulting image will have the dimensions **800 px × 800 px**, proportionally upscaled so that neither dimension exceeds the defined limits.
- **Smart crop variant** – Images are cropped based on the focal point. Marketers can fine-tune the smart crop variants by [selecting a focal point](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md#change-image-focal-point) to guide automatic cropping or by [adjusting the crop manually](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md#crop-variants-manually). To ensure the image meets the specified dimensions, the system may upscale or downscale the final variant as needed.
> **Info:** The maximum supported number of image variant definitions is 63. Exceeding this limit may result in unexpected behavior.
>
> When using _Scaled variants_, images can be scaled up if the specified dimensions exceed the original image dimensions. This may result in blurry images or increased file sizes due to image upscaling. Developers who need to avoid upscaling should handle this behavior within their implementation.
To define a new variant for images in the system:
1. In the **Content types** application, open the **Asset configurations → Image variants** tab.
2. **Add new variant** definition.
3. Select the variant type and fill in the variant's properties.
4. **Save** the changes.
All images in the system become available in the defined variant shortly, after the automatically triggered _Update asset variants_ [system scheduled task](https://docs.kentico.com/documentation/developers-and-admins/customization/scheduled-tasks.md) completes. Users can then further [manage individual variants](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md#image-variants) of their images.
> **Tip:** Marketers typically won’t use every variant of every image. To prevent unnecessary storage use, the binary file for each variant is generated only when the variant is [accessed](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-content-items.md#retrieve-image-variants) for the first time.
>
> ---
>
> Variants accessed for the first time while the application runs in read-only mode are generated into a temporary local cache instead. See [Read-only deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md#content-item-asset-variants).
#### Use image variants
To correctly display image variants on the pages of a [website channel](https://docs.kentico.com/documentation/business-users/website-content.md), developers can either:
- (Recommended) Use the `kxp-img`, `kxp-img-dimensions` and `kxp-img-variant` attribute Tag Helpers to render the image variant in your views. For more information on Tag Helper usage, see [Reference - Tag Helpers](https://docs.kentico.com/documentation/developers-and-admins/development/reference-tag-helpers.md#attribute-tag-helpers-images).
```cshtml
@*
- kxp-img – Renders markup of the `src` or `srcset` attributes with
the image URL as their value. Accepts a ContentItemAsset object representing the image.
- kxp-img-dimensions – Renders markup of the `width` and `height`
attributes based on the dimensions of the image variant.
- kxp-img-variant – Specifies the code name of the image variant to be used.
*@
@addTagHelper Kentico.Content.Web.Mvc.ContentItemAssetImageTagHelper, Kentico.Content.Web.Mvc.ContentItemAssetPictureSourceTagHelper, Kentico.Content.Web.Mvc
@* Works well with both scaled and smart crop image variants *@
@* Best used with smart-crop variants to address art direction scenarios *@
```
- Retrieve and use the variant's URL and other properties in your views. For more information on image variant retrieval, see [Retrieve content items](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-content-items.md#retrieve-image-variants).
```csharp title="Retrieve image variants"
using CMS.ContentEngine;
// Retrieves a content item asset
// ...
// Accesses the asset object in the ImageFile property of the asset's content type
ContentItemAsset asset = myAsset.ImageFile;
// Accesses the properties of an image variant with the 'Hero' code name
if (asset.Metadata.Variants.ContainsKey("Hero")){
int variantWidth = asset.Metadata.Variants["Hero"].Width;
int variantHeight = asset.Metadata.Variants["Hero"].Height;
string variantType = asset.metadata.Variants["Hero"].TransformationType;
string variantUrl = asset.VariantUrls["Hero"];
}
```
#### Image variant URL structure
Image variant URLs build on top of the standard base asset URL by inserting the variant's code name into the path and appending it to the file name. This means that a base URL like:
_/getContentAsset/7dd94187-f658-48cd-8a59-308e55b154f1/cc721195-df8f-4799-b974-5ade63036cab/the-resilient-robusta.webp_
turns into the following for a variant called _MyImageVariant-Wide_:
_/getContentAsset/7dd94187-f658-48cd-8a59-308e55b154f1/cc721195-df8f-4799-b974-5ade63036cab/MyImageVariant-Wide/the-resilient-robusta\_MyImageVariant-Wide.webp_
In general, every variant URL follows this structure: _/getContentAsset////._, where each segment represents:
- `content-item-guid` – the GUID of the content item that the asset is attached to.
- `asset-field-guid` – the GUID of the `Content item asset` field storing the asset.
- `variant-code-name` – the code name of the image variant (e.g., _MyImageVariant-Wide_).
- `file-name_variant-code-name.file-extension` – the original file name with the variant code name appended as a suffix (e.g., _image\_MyImageVariant-Wide.jpg_ derived from a source file named _image.jpg_).
#### Edit image variant definitions
To edit an image variant's definition:
1. In the **Content types** application, open the **Asset configurations → Image variants** tab.
2. Edit the variant's properties as needed.
3. **Save** the changes.
The image variant is updated accordingly to its new definition in all images after the automatically triggered `Update asset variants` [system scheduled task](https://docs.kentico.com/documentation/developers-and-admins/customization/scheduled-tasks.md) completes.
#### Delete image variant definitions
If a specific image variant should no longer be used in your project, you can remove its definition:
1. In the **Content types** application, open the **Asset configurations → Image variants** tab.
2. **Delete** () the image variant's definition.
3. **Save** the changes.
After the image variant's definition is deleted, the [variant itself](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md#image-variants) remains visible when adjusting images but becomes read-only. Your developers should now update their code to no longer [use](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-content-items.md#retrieve-image-variants) the deleted variant.
## Work with content types in custom code
The system provides [code generation support](https://docs.kentico.com/documentation/developers-and-admins/api/generate-code-files-for-system-objects.md) for objects that contain custom fields. The resulting generated classes are plain data transfer objects that work seamlessly with Xperience's [data retrieval API](https://docs.kentico.com/documentation/developers-and-admins/api/content-item-api.md).
Whenever you modify a content type's fields (add or remove fields, change the field's data type), you need to regenerate the corresponding classes using the code generator. This keeps the models consistent with the content type's database definition.