Adding New Components and Customizing Existing Ones

Introduction

At some point, every project faces the need to add new, highly customized components that must seamlessly integrate into the core structure, preserving its benefits and update capability. It’s also crucial to be able to override certain logic within existing core components, enabling you to reuse them while adding tailored functionality.

In this guide, we’ll show you how to connect your custom components in code and on the canvas, as well as how to wrap core components in custom wrappers to extend or override their default behavior.

Components Registration and Resolver Structure

Each component used on the canvas must be registered and passed to the main resolveComponent function for display.

We recommend structuring the component resolver with two separate mappers: one for core CSK components and another for custom components.

This setup keeps core and custom components organized independently, allowing for safe updates and the flexibility to easily add or remove components as needed in the application.

We’ve taken care of this for you, so you’ll already see this separation in the main components file: src/components/index.ts.

import { cskComponentsMapping } from '@/components/canvas'; import { customComponentsMapping } from '@/components/custom-canvas'; import createComponentResolver, { ComponentMapping } from '@/utils/createComponentResolver'; const componentsMapping: ComponentMapping = { ...cskComponentsMapping, ...customComponentsMapping, }; const componentResolver = createComponentResolver(componentsMapping); export default componentResolver;

Adding New Client's Components

To add your own component and custom logic, start by adding it to the canvas side, defining all parameters, slots, and additional settings. Then, add it in code to capture, process, and display the necessary information from the canvas. Finally, be sure to register the component for proper integration.

For your convenience, we’ve included a simple example demonstrating how to add and register a component in the CSK base setup. This example provides everything you need, with added comments to highlight key areas such as the parameter list, slots, and a designated space for custom logic.
src/components/custom-canvas/CustomComponent.tsx

import { FC } from 'react'; import { ComponentProps, UniformSlot, UniformText } from '@uniformdev/canvas-next-rsc/component'; // Here, you can add parameters to be used on the canvas side. export type CustomComponentParameters = { displayName?: string; }; // Here, you can add slots names to be used on the canvas side. enum CustomComponentSlots { CustomComponentContent = 'customComponentContent', } type CustomComponentProps = ComponentProps<CustomComponentParameters, CustomComponentSlots>; const CustomComponent: FC<CustomComponentProps> = ({ component, context, slots }) => ( // Your implementation of the component logic <div> <UniformText placeholder="Text goes here" parameterId="displayName" as="h1" component={component} context={context} /> <UniformSlot data={component} context={context} slot={slots.customComponentContent} /> </div> ); export default CustomComponent;

Registration:
src/components/custom-canvas/index.ts

import { ComponentMapping } from '@/utils/createComponentResolver'; import Container from './Container'; import CustomComponent from './CustomComponent'; // Here, you can add your own component or customize an existing CSK component with your logic or styles. export const customComponentsMapping: ComponentMapping = { // This is a simple example of how you can add your own components. customComponent: CustomComponent, // This is an overridden CSK Container component. container: Container, };

Customizing Existing Core Components

To customize a core component, you first need to import the existing component that you wish to override. Next, modify its properties or add any additional ones as needed. You have the freedom to customize further, allowing you to implement the necessary functionality on top of the existing component.

To help you get started, we’ve also included an example of how this can be done.
src/components/custom-canvas/Container.tsx

import { FC } from 'react'; import CSKContainer, { ContainerProps as CSKContainerProps } from '@/components/canvas/Container'; // This is an example of how you can override an existing CSK component based on the Container component. const Container: FC<CSKContainerProps> = props => <CSKContainer {...props} />; export default Container;

When registering your component, it's important to use the same name as the existing component. Below, you can see an example of how to override the Container component.
src/components/custom-canvas/index.ts

Conclusion

We explored how to add new components or customize existing ones using simple examples available in the core CSK. We also reviewed and clarified the key decisions involved in structuring component registration.