Theming

This guide details the two primary methods for customizing the visual appearance (colors, fonts, border radius, etc.) of the @socotra/ec-react-components library.

Method 1: Theming with Tailwind CSS and shadcn/ui (Recommended)

The most powerful and recommended method for customization is to integrate the components directly into a project that uses Tailwind CSS and has shadcn/ui initialized. Because our components are built with these tools, they will automatically adopt the theme you define in your application.

This approach gives you complete control over the library’s look and feel, ensuring it seamlessly matches your application’s design system.

Step 1: Install shadcn/ui

If you haven’t already, install shadcn/ui in your host application by following the official guide on the shadcn/ui website <https://ui.shadcn.com/docs/installation>__. This process will create a components.json file and set up your project to use CSS variables for theming.

Step 2: Configure tailwind.config.js

Ensure your project’s tailwind.config.js is configured to scan the @socotra/ec-react-components library for Tailwind classes. This allows Tailwind to include the necessary styles in its build process.

// tailwind.config.js
module.exports = {
	//...
	content: [
		'./app/**/*.{ts,tsx}',
		'./components/**/*.{ts,tsx}',
		'./node_modules/@socotra/ec-react-components/dist/**/*.js', // Add this line
	],
	//...
};

Step 3: Customize Your Theme

Now, you can customize your theme by modifying the CSS variables that shadcn/ui uses. These are typically located in your main CSS file (e.g., app/globals.css). By changing these variables, you can alter colors, border radii, fonts, and more across your entire application and within the Socotra components.

For example, to change the primary brand color:

/* app/globals.css */
@layer base {
	:root {
		/* ... other variables */
		--primary: 222.2 84% 4.9%; /* Change this value */
		--primary-foreground: 210 40% 98%; /* And this one */
		--radius: 0.5rem; /* Change border radius */
		/* ... etc. */
	}
}

You can use the theme creator on the shadcn/ui website to easily generate your desired color palette.

Step 4: Do Not Import the Pre-built CSS

Important: When using this method, do not import the library’s pre-built stylesheet (@socotra/ec-react-components/dist/style.css). Your project’s Tailwind build process will handle all styling, and importing the CSS file will lead to style conflicts.

Method 2: Basic CSS Import (Without Tailwind)

If your project does not use Tailwind CSS, you can still use the components by importing the compiled stylesheet. This method is simpler but offers no customization options.

Usage

In the root of your application (e.g., main.tsx or _app.tsx), import the style.css file directly from the package:

import '@socotra/ec-react-components/dist/style.css';

This will apply the default, pre-packaged Socotra theme to the components. With this method, you cannot change colors, fonts, or other themeable properties without manually overriding CSS classes, which is not recommended.

Method 3: Per-Component Style Overrides (Advanced)

For the most granular level of control, you can pass a styles prop directly to a form component. This allows you to override the styles for specific UI elements within that single form instance, without affecting any other forms in your application.

This method is ideal when you need to make a one-off adjustment to a particular form’s layout or appearance. The styles prop accepts an array of StyleDefinition objects. Each object targets a specific part of the form’s UI and applies one or more CSS or Tailwind classes.

Usage

Pass an array to the styles prop of a form component like QuoteForm, ElementForm, etc.

<QuoteForm
	styles={[
		{ name: 'control.label', classNames: ['font-bold', 'text-blue-600'] },
		{ name: 'control.input', classNames: ['bg-gray-50'] },
	]}
/>

Supported Style Targets

The name property of the StyleDefinition object can be one of the following values, each targeting a specific part of the UI generated by @jsonforms.