Props are configurable fields that make components user-friendly and simplify content creation. 

Props are used to:

• Create fields that can be filled without editing the code. For example, Title, Description, and Button Text.
• Select colors, sizes, alignments, or behaviors from pre-defined options.
• Present options as familiar UI controls such as dropdowns, toggles.
• Set appropriate defaults so that components work well out-of-the-box.

For example: A Featured Content component might have configurable props for headline text, subtitle, image, background color, and button label without showing the underlying markup.

Multi-value properties enable component builders to configure a prop to store multiple entries instead of a single value. This configuration is essential for components requiring collections of data, such as galleries, navigation lists, or data series.

Accessing props

Props are managed within the code Editor. To navigate to this interface, select a component from either the code-based components menu or the Component Library. Both access methods open the same editor workspace.

To access props for code-based components:

1. Access your site

2. On the top right, click Edit to open Drupal Canvas.

3. In the left toolbar, click the Code </> icon to open the code-based components menu.

4. Select the component in the list to which you want to add or edit a prop. 

   The system opens the code Editor for the component and displays the Preview and Component data panels on the right.

5. In the Component data panel on the right, locate the Props tab.

To access props for components in the Component Library:

1. Access your site.

2. On the top right, click Edit to open Drupal Canvas.

3. In the left toolbar, click the Library (+) icon to open the Component Library.

4. On the Components tab, locate the component in the list to which you want to add or edit a prop.

5. Click the Ellipses (...) icon for the component.

6. Select Edit code from the menu options. 

   The system opens the code Editor of the component and displays the Preview and Component data panels on the right.

7. In the Component data panel on the right, locate the Props tab.

Adding a prop

To add a prop:

1. Access the Props tab for the component for which you want to create a prop.

2. Click + Add.

3. Define the prop name, type, and associated configuration values. The available configuration fields vary depending on the selected prop type.

   Note

   When you select Content entity reference, the standard configuration fields are replaced by an Add type button that launches the Content Relationship dialog box. Note that these props do not support required settings, example values, or multiple values.

   The prop name is automatically converted to camelCase. For example, if the prop name is Heading Text, it can be accessed in the component as headingText.

4. (Optional) Click + Add to add additional props.

Setting up multi-value props

The multi-value option is available only for specific prop types. Supported types include Text, Link, Image, Video, Date and time, Integer, Number, List: Text, and List: Integer. The system does not support multi-value properties for Formatted Text and Boolean types. For unsupported types, the system hides the Allow multiple values option from the interface.

Content entity reference props are limited to a single value; the Allow multiple values option is not supported. To reference multiple entities, you must either add a separate prop for each entity or place the component multiple times.

To set up a multi-value prop:

1. Access the Props tab for the component for which you want to add multiple values.
2. Select a supported prop type.

3. Select the Allow multiple values checkbox.

   Note

   The system unchecks this option by default. If you change the prop type, the system resets the checkbox to unchecked.

4. Select whether the list is Limited or Unlimited.
   • Limited values: Specify a maximum number of values.
     • The system displays a fixed number of rows.
     • You can drag and drop to reorder the rows.
     • You cannot delete rows because the count is fixed.
   • Unlimited values: Click + Add value to add additional rows.
     • Each row displays a Delete icon for deletion.
     • You can drag and drop to reorder the rows.

Editing existing props

Site builders and developers can expand the capabilities of components already placed on pages. You can evolve these components while they remain in use across your site. The system manages the transition of existing content to the new component definitions to ensure data integrity while providing flexibility.  

When editing a component that is already in use, you can perform the following actions:

• Add optional props: Add new optional properties to a component. Drupal Canvas does not backfill example values to existing instances. The new settings display the next time a content creator edits that specific component.

• Add required props: Add a required prop to an in-use component if an example or default value is provided. Drupal Canvas uses the default value to auto-fill existing instances so the page does not break. Changing a prop from optional to required follows this same rule and must have a default value present.

• Make props optional: Change an existing prop from required to optional.

• Update values: Update the default or example values for props. Drupal Canvas does not backfill these updates to instances on pages you have already saved. Because saving a page stores a copy of the current value for that instance, subsequent changes to the default value will not affect that content.

• Delete props: Remove props that are no longer needed.

However, to preserve data integrity, there are strict limitations. After you add a component to the library, you cannot perform the following actions on an existing prop:

• Change the Prop name.

• Change the Type of the prop.

• Change a single-value prop to a multi-value prop. You cannot select the Allow multiple values checkbox after you create the prop.

To achieve any of these restricted changes, you must delete the existing prop and create a new prop with the desired configuration.

To edit props on components that are already in use across your site:

1. Access the Props tab for the component for which you want to edit the prop.

2. Edit the prop as needed.

3. Publish the changes.

To relocate a prop:

1. Click and hold the Drag handle icon of the prop you want to relocate.

   The system displays the hand icon.

2. Drag and drop the prop in the new location in the props list.

3. Publish the changes.

Deleting a prop

If a feature prop is no longer needed, you can remove it from the code component. The database retains the data only until you publish the content again. This retention prevents data loss from an accidental deletion. However, the system no longer renders this data on the live site or displays it in the Drupal Canvas Editor.

To delete a prop:

1. Access the Props tab and locate the prop that you want to delete.

2. Click the Delete icon associated with the prop. 

   The system deletes the prop.

Available prop types

The following table provides example implementations of Drupal Canvas code components for available prop types.

const Component = ({ text }) => {
  return (
    {text}
  );
};

 const Component = ({ texts = [] }) => {
  if (!Array.isArray(texts) || !texts.length) return null;
  return (
    <div>
      {texts.map((text, i) => (
        <div key={i}>{text}</div>
      ))}
    </div>
  );
};

import FormattedText from "@/lib/FormattedText";
const Component = ({ formattedText }) => {
  return (
    <FormattedText>
      {formattedText}
    </FormattedText>
  );
};

const Component = ({ link }) => {
  return (
    <a href={link}>Link text</a>
  );
};

const Component = ({ links = [] }) => {
  if (!Array.isArray(links) || !links.length) return null;
  return (
    <div>
      {links.map((link, i) => (
        <a key={i} href={link}>
          {link}
        </a>
      ))}
    </div>
  );
};

import Image from "@/lib/Image";
const Component = ({ image }) => {
  return (
    <Image {...image} />
  );
};

import { Image } from 'drupal-canvas';
const Component = ({ images = [] }) => {
  if (!Array.isArray(images) || !images.length) return null;
  return (
    <div>
      {images.map((img, i) =>
        img?.src ? (
          <Image key={i} src={img.src} alt={img.alt} width={img.width} height={img.height} />
        ) : null
      )}
    </div>
  );

const Component = ({ videos = [] }) => {
  if (!Array.isArray(videos) || !videos.length) return null;
  return (
    <div>
      {videos.map((video, i) =>
        video ? (
          <video key={i} controls width="100%">
            <source src={video} />
          </video>
        ) : null
      )}
    </div>
  );
};

Content entity reference props connect a component to existing content, ensuring it always displays live, up-to-date information without data duplication. These props deliver an object containing your selected fields. If no content is referenced or the referenced content is deleted, the prop value is null. For detailed field-selection steps, object structure, and developer guidance, see Content entity reference props.

Props

Props are configurable fields that make components user-friendly and simplify content creation. 

Props are used to:

• Create fields that can be filled without editing the code. For example, Title, Description, and Button Text.
• Select colors, sizes, alignments, or behaviors from pre-defined options.
• Present options as familiar UI controls such as dropdowns, toggles.
• Set appropriate defaults so that components work well out-of-the-box.

For example: A Featured Content component might have configurable props for headline text, subtitle, image, background color, and button label without showing the underlying markup.

Multi-value properties enable component builders to configure a prop to store multiple entries instead of a single value. This configuration is essential for components requiring collections of data, such as galleries, navigation lists, or data series.

Accessing props

Props are managed within the code Editor. To navigate to this interface, select a component from either the code-based components menu or the Component Library. Both access methods open the same editor workspace.

To access props for code-based components:

1. Access your site

2. On the top right, click Edit to open Drupal Canvas.

3. In the left toolbar, click the Code </> icon to open the code-based components menu.

4. Select the component in the list to which you want to add or edit a prop. 

   The system opens the code Editor for the component and displays the Preview and Component data panels on the right.

5. In the Component data panel on the right, locate the Props tab.

To access props for components in the Component Library:

1. Access your site.

2. On the top right, click Edit to open Drupal Canvas.

3. In the left toolbar, click the Library (+) icon to open the Component Library.

4. On the Components tab, locate the component in the list to which you want to add or edit a prop.

5. Click the Ellipses (...) icon for the component.

6. Select Edit code from the menu options. 

   The system opens the code Editor of the component and displays the Preview and Component data panels on the right.

7. In the Component data panel on the right, locate the Props tab.

Adding a prop

To add a prop:

1. Access the Props tab for the component for which you want to create a prop.

2. Click + Add.

3. Define the prop name, type, and associated configuration values. The available configuration fields vary depending on the selected prop type.

   Note

   When you select Content entity reference, the standard configuration fields are replaced by an Add type button that launches the Content Relationship dialog box. Note that these props do not support required settings, example values, or multiple values.

   The prop name is automatically converted to camelCase. For example, if the prop name is Heading Text, it can be accessed in the component as headingText.

4. (Optional) Click + Add to add additional props.

Setting up multi-value props

The multi-value option is available only for specific prop types. Supported types include Text, Link, Image, Video, Date and time, Integer, Number, List: Text, and List: Integer. The system does not support multi-value properties for Formatted Text and Boolean types. For unsupported types, the system hides the Allow multiple values option from the interface.

Content entity reference props are limited to a single value; the Allow multiple values option is not supported. To reference multiple entities, you must either add a separate prop for each entity or place the component multiple times.

To set up a multi-value prop:

1. Access the Props tab for the component for which you want to add multiple values.
2. Select a supported prop type.

3. Select the Allow multiple values checkbox.

   Note

   The system unchecks this option by default. If you change the prop type, the system resets the checkbox to unchecked.

4. Select whether the list is Limited or Unlimited.
   • Limited values: Specify a maximum number of values.
     • The system displays a fixed number of rows.
     • You can drag and drop to reorder the rows.
     • You cannot delete rows because the count is fixed.
   • Unlimited values: Click + Add value to add additional rows.
     • Each row displays a Delete icon for deletion.
     • You can drag and drop to reorder the rows.

Editing existing props

Site builders and developers can expand the capabilities of components already placed on pages. You can evolve these components while they remain in use across your site. The system manages the transition of existing content to the new component definitions to ensure data integrity while providing flexibility.  

When editing a component that is already in use, you can perform the following actions:

• Add optional props: Add new optional properties to a component. Drupal Canvas does not backfill example values to existing instances. The new settings display the next time a content creator edits that specific component.

• Add required props: Add a required prop to an in-use component if an example or default value is provided. Drupal Canvas uses the default value to auto-fill existing instances so the page does not break. Changing a prop from optional to required follows this same rule and must have a default value present.

• Make props optional: Change an existing prop from required to optional.

• Update values: Update the default or example values for props. Drupal Canvas does not backfill these updates to instances on pages you have already saved. Because saving a page stores a copy of the current value for that instance, subsequent changes to the default value will not affect that content.

• Delete props: Remove props that are no longer needed.

However, to preserve data integrity, there are strict limitations. After you add a component to the library, you cannot perform the following actions on an existing prop:

• Change the Prop name.

• Change the Type of the prop.

• Change a single-value prop to a multi-value prop. You cannot select the Allow multiple values checkbox after you create the prop.

To achieve any of these restricted changes, you must delete the existing prop and create a new prop with the desired configuration.

Important

Always preview the impact of component changes in Drupal Canvas before you publish. 

Changes made to an existing prop do not display on the live site until you publish the page.

 

To edit props on components that are already in use across your site:

1. Access the Props tab for the component for which you want to edit the prop.

2. Edit the prop as needed.

3. Publish the changes.

To relocate a prop:

1. Click and hold the Drag handle icon of the prop you want to relocate.

   The system displays the hand icon.

2. Drag and drop the prop in the new location in the props list.

3. Publish the changes.

Deleting a prop

If a feature prop is no longer needed, you can remove it from the code component. The database retains the data only until you publish the content again. This retention prevents data loss from an accidental deletion. However, the system no longer renders this data on the live site or displays it in the Drupal Canvas Editor.

To delete a prop:

1. Access the Props tab and locate the prop that you want to delete.

2. Click the Delete icon associated with the prop. 

   The system deletes the prop.

Available prop types

The following table provides example implementations of Drupal Canvas code components for available prop types.

Name	Example Usage
Text	Single: copy const Component = ({ text }) => {  return (    {text}  ); }; Multiple: copy  const Component = ({ texts = [] }) => { if (!Array.isArray(texts) || !texts.length) return null; return ( <div> {texts.map((text, i) => ( <div key={i}>{text}</div> ))} </div> ); };
Formatted Text	copy import FormattedText from "@/lib/FormattedText"; const Component = ({ formattedText }) => {  return (    <FormattedText>     {formattedText}    </FormattedText>  ); };
Link	Single:  copy const Component = ({ link }) => {  return (    <a href={link}>Link text</a>  ); }; Multiple: copy const Component = ({ links = [] }) => { if (!Array.isArray(links) || !links.length) return null; return ( <div> {links.map((link, i) => ( <a key={i} href={link}> {link} </a> ))} </div> ); };
Image	Single:  copy import Image from "@/lib/Image"; const Component = ({ image }) => {  return (    <Image {...image} />  ); }; Multiple: copy import { Image } from 'drupal-canvas'; const Component = ({ images = [] }) => {  if (!Array.isArray(images) || !images.length) return null;  return (    <div>      {images.map((img, i) =>        img?.src ? (          <Image key={i} src={img.src} alt={img.alt} width={img.width} height={img.height} />        ) : null      )}    </div>  );
Video	Single:  Multiple: copy const Component = ({ videos = [] }) => {  if (!Array.isArray(videos) || !videos.length) return null;  return (    <div>      {videos.map((video, i) =>        video ? (          <video key={i} controls width="100%">            <source src={video} />          </video>        ) : null      )}    </div>  ); };

Content entity reference props connect a component to existing content, ensuring it always displays live, up-to-date information without data duplication. These props deliver an object containing your selected fields. If no content is referenced or the referenced content is deleted, the prop value is null. For detailed field-selection steps, object structure, and developer guidance, see Content entity reference props.