Skip to content
Arc XP

How to customize a block

This guide walks you through customizing Arc blocks in your Themes-based repository, offering a faster alternative to building custom blocks from scratch.

Custom blocks are necessary when the out-of-the-box (OOTB) Arc blocks don’t fully meet your design, styling, or functionality requirements. However, you can still leverage Arc Themes components to avoid duplicating functionality already maintained by Arc XP.

Prerequisites

Before customizing an Arc block, ensure you have the following:

High-level workflow

The process for customizing Arc blocks comprises five fundamental steps:

  1. First, check whether an existing Arc block meets your requirements. If one is available that mostly fits your needs, consider using it with minor styling adjustments using the provided tokens. If a block’s functionality is sufficient, no further steps are needed. For Outbound Feeds blocks, begin at Step 2

  2. Fork your chosen block keeping only the essential files

  3. Ensure compatibility of all dependencies for your custom block in the package.json file.

  4. Customize your forked block based on desired functionality

  5. Deploy your custom block

Step-by-step workflow

This step-by-step workflow for customizing blocks is divided into different upgrade paths:

  • Partial upgrade path updates only the Arc components used within your custom blocks.
  • Off the upgrade path means you’re responsible for manually updating your custom blocks and components.

Full upgrade path

Partial upgrade path or off upgrade path (full custom)

Before proceeding, review the diagram on Deciding when to use an out-of-the-box block versus a custom block. Partial upgrade and off upgrade paths mean that you are responsible for maintaining and updating your custom code.

Fork the block

Arc XP recommends starting from an Arc block with a process known as forking or ejecting. Customizing an existing block ensures maximum code reusability.

To fork a block, take the following steps:

  1. From the arc-themes-blocks repository, copy the block directory, including its children and styles (you can exclude storybook files). Ensure to look at the latest branch that matches the Themes version you are using.

  2. If the block imports from the @wpmedia/arc-themes-components package, verify to list the package as a dependency in your package.json file.

For outbound feeds, use the source code from the feed-components GitHub repository as starter scaffolding for custom blocks, as mentioned in the Outbound Feeds ejecting a block Arc XP University course.

Ensure dependency compatibility

Ensure you have all dependencies for the forked blocks in your main package.json file for seamless integration within your feature pack.

Customize the forked block

Follow the Creating a custom block with styling guide to make styling changes and stay on the partial upgrade path.

If none of the available styling tokens or components from @wpmedia/arc-themes-components meet your requirements, you must create fully custom components, which are off the upgrade path.

Deploying custom blocks

Follow the How to deploy a bundle guide.

Best practices

  • Use a unique name for your custom block
    Give your custom block a unique name that differentiates it from the original Arc block. Using a distinct name avoids conflicts and confusion between your custom and original blocks. If you choose to retain the same name, remove the original block from the blocks.json file.

  • Test before full deployment
    Test your custom block in the sandbox environment before full deployment. This enables you to identify and rectify any errors or glitches that might have occurred during development. The deployment process is a critical phase in customizing Arc blocks. Proper execution ensures your custom blocks work seamlessly within your project.

Themes against non-Themes

If you do not use Themes, you can still use the Arc blocks as a framework for your own blocks. However, it is important to ensure the blocks have all the necessary dependencies.