---
title: "Props"
date: "2025-07-25T07:12:35+00:00"
summary: "Simplify content creation with configurable props. Learn how to use text, media, and lists to make user-friendly components."
image:
type: "page"
url: "/acquia-source/props"
id: "d5702cb8-21bc-4c4f-8c9f-cdc810fe89a6"
---

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.

![acquia-source\_props](https://acquia.widen.net/content/zqlq87xtaf/web/30805_acquia-source_props.png?w=720&v=27a3f8d7-867b-4653-be26-2e72da56564f&itok=ZH3AfnYg)

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](https://docs.acquia.com/node/69836#access-a-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](https://docs.acquia.com/node/69836#access-a-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](https://accessing-props) 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](https://accessing-props) 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.
        *   You can delete rows as needed.

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](https://accessing-props) 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](https://accessing-props) 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:**

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

**Multiple:**

     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

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

Link

**Single:** 

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

**Multiple:**

    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:** 

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

**Multiple:**

    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:**

    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>
      );
    };

Boolean

    const Component = ({ boolean }) => {
      return (
        {boolean && <h1>Boolean: checked</h1>}
        {!boolean && <h1>Boolean: unchecked</h1>}
      );
    };

Integer

**Single:** 

    const Component = ({ integer }) => {
      return (
        <h1 style=`padding-top: ${integer}px`>Heading with spacing</h1>
      );
    };

**Multiple:**

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

Number

**Single:** 

**Multiple:**

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

List: text

**Single:** 

    import FormattedText from "@/lib/FormattedText";
    import { cva } from 'class-variance-authority';
    
    const variants = cva('', {
      variants: {
        layout: {
          left: 'text-left',
          center: 'text-center',
        },
      },
      defaultVariants: {
        layout: 'left',
      },
    });
    const Component = ({ listText }) => {
      return (
        <h1 className={variants({ layout: listText })>Heading text</h1>
      );

**Multiple:**

     const Component = ({ items = [] }) => {
      if (!Array.isArray(items) || !items.length) return null;
      return (
        <ul>
          {items.map((item, i) => (
            <li key={i}>{item}</li>
          ))}
        </ul>
      );
    };

List: integer

**Single:**

    const Component = ({ listInteger }) => {
      return (
        <h1 style=`padding-top: ${listInteger}px`>Heading with spacing</h1>
      );
    };

**Multiple:**

    const Component = ({ items = [] }) => {
      if (!Array.isArray(items) || !items.length) return null;
      return (
        <ul>
          {items.map((item, i) => (
            <li key={i}>{item}</li>
          ))}
        </ul>
      );
    };

Date and time

**Single:** 

    const Component = ({ dateTime }) => {
      return (
        <div>
          {dateTime ? new Date(dateTime).toLocaleString() : ''}
        </div>
      );
    };

**Multiple:**

    const Component = ({ dateTimes = [] }) => {
      if (!Array.isArray(dateTimes) || !dateTimes.length) return null;
      return (
        <div>
          {dateTimes.map((dateTime, i) => {
           const formatted = dateTime ? new Date(dateTime).toLocaleString() : '';
            return formatted ? <div key={i}>{formatted}</div> : '';
          })}
        </div>
      );
    };

Content entity reference

    const Component = ({ article }) => { if (!article) return null; return <h3>{article.label}</h3>; };

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](/acquia-source/content-entity-reference-props "Content entity reference props").