The best practices for reading and replacing selected content.

It often makes sense to update the user interface based on whether something is selected. For example, if nothing is selected, an app should disable any elements that are only relevant when something is selected.

Technically, there's nothing stopping apps from replacing content:

  • as soon as it's selected
  • on some kind of schedule, such as š‘„ seconds after selection

However, both of these are surprising behaviors that may confuse users. The better approach is for apps to only replace content when there is clear intent, such as when the user clicks a button.

Replacing content can be a time-consuming process, such as when uploading a replacement image. In these cases, show the appropriate loading states, such as loading spinners or progress bars. To learn more, see Loading.


The selection.registerOnChange method assumes the app wants to handle multiple elements at once. If this is not the case, show an alert and disable any relevant buttons when more than one element is selected. An example of when this might be the case is when the app performs resource-intensive tasks, such as tasks involving generative AI.

Generally, if an app can support multiple selections, it should.

If an app replaces an image, it must pass the ref of the original image into the upload method via the parentRef property. This ensures that Canva can keep track of the original asset and adhere to any licensing requirements.