Styling

Customize the appearance of Cedar-OS components

Cedar-OS provides comprehensive styling options through the stylingSlice and integrates seamlessly with Tailwind CSS. This guide covers how to customize the appearance of Cedar components and ensure proper Tailwind configuration.

Tailwind CSS Setup

Cedar-OS components use Tailwind CSS for styling. To ensure all Cedar styles work correctly, you need to configure Tailwind to scan Cedar’s component files.

Tailwind 4.0+ Configuration

If you’re using Tailwind CSS 4.0 or later, add the following @source directive to your main CSS file:

/* app/globals.css or your main CSS file */
@import 'tailwindcss';

/* Add Cedar-OS components to Tailwind's content sources */
@source "../node_modules/cedar-os/**/*.{js,ts,jsx,tsx}";

Tailwind 3.x Configuration

For Tailwind CSS 3.x, add Cedar’s paths to your tailwind.config.js:

// tailwind.config.js
module.exports = {
	content: [
		// Your app's content paths
		'./src/pages/**/*.{js,ts,jsx,tsx,mdx}',
		'./src/components/**/*.{js,ts,jsx,tsx,mdx}',
		'./src/app/**/*.{js,ts,jsx,tsx,mdx}',
		'./src/lib/**/*.{js,ts,jsx,tsx,mdx}',
		'./src/**/*.{js,ts,jsx,tsx}',

		// Add Cedar-OS component paths
		'./node_modules/cedar-os/**/*.{js,ts,jsx,tsx}',
	],
	// ... rest of your config
};

Using the Styling Slice

Cedar-OS includes a stylingSlice that manages global styling configuration for all Cedar components. This allows you to customize colors, dark mode, and other visual properties across your entire application.

Accessing Styling State

import { useCedarStore } from 'cedar-os';

function MyComponent() {
	const { styling, setStyling, toggleDarkMode } = useCedarStore();

	return (
		<div>
			<p>Current theme: {styling.darkMode ? 'Dark' : 'Light'}</p>
			<p>Primary color: {styling.color}</p>
			<button onClick={toggleDarkMode}>Toggle Dark Mode</button>
		</div>
	);
}

Styling Configuration

The styling slice provides the following configuration options:

interface StylingConfig {
	darkMode: boolean; // Enable/disable dark mode
	color: string; // Primary color (hex format)
	secondaryColor: string; // Secondary color (hex format)
	accentColor: string; // Accent color (hex format)
}

Setting Custom Colors

You can update the color scheme programmatically:

import { useCedarStore } from 'cedar-os';

function ThemeCustomizer() {
	const { setStyling } = useCedarStore();

	const applyBrandColors = () => {
		setStyling({
			color: '#3B82F6', // Blue primary
			secondaryColor: '#1E40AF', // Darker blue
			accentColor: '#F59E0B', // Amber accent
		});
	};

	const applyDarkTheme = () => {
		setStyling({
			darkMode: true,
			color: '#6366F1', // Indigo for dark mode
			secondaryColor: '#4F46E5',
			accentColor: '#EC4899', // Pink accent
		});
	};

	return (
		<div>
			<button onClick={applyBrandColors}>Apply Brand Colors</button>
			<button onClick={applyDarkTheme}>Apply Dark Theme</button>
		</div>
	);
}

Component-Level Styling

Using Styled Components

Cedar components automatically respond to the global styling configuration. For example, the chat components will use your configured colors:

import { FloatingCedarChat } from '@/chatComponents/FloatingCedarChat';
import { useCedarStore } from 'cedar-os';

function StyledChat() {
	const { setStyling } = useCedarStore();

	// Set custom colors before rendering
	useEffect(() => {
		setStyling({
			color: '#8B5CF6', // Purple
			secondaryColor: '#7C3AED',
			accentColor: '#F97316', // Orange
		});
	}, []);

	return <FloatingCedarChat side='right' title='Support Chat' />;
}

CSS Variables

Cedar-OS components use CSS variables that integrate with Tailwind’s design system. These variables are automatically updated when you change the styling configuration:

/* These variables are set by Cedar-OS */
:root {
	--cedar-primary: /* Your primary color */ ;
	--cedar-secondary: /* Your secondary color */ ;
	--cedar-accent: /* Your accent color */ ;
	--cedar-background: /* Background color based on theme */ ;
	--cedar-foreground: /* Text color based on theme */ ;
}

Utility Functions

Cedar-OS provides several utility functions for working with colors:

Color Manipulation

import {
	desaturateColor,
	getShadedColor,
	getLightenedColor,
	getTextColorForBackground,
} from 'cedar-os';

// Desaturate a color (reduce vibrancy)
const mutedBlue = desaturateColor('#3B82F6');

// Create a darker shade
const darkBlue = getShadedColor('#3B82F6', 0.2); // 20% darker

// Create a lighter tint
const lightBlue = getLightenedColor('#3B82F6', 0.3); // 30% lighter

// Get appropriate text color for a background
const textColor = getTextColorForBackground('#3B82F6'); // Returns white or black

Class Name Utilities

Cedar uses the cn utility (similar to clsx) for combining class names:

import { cn } from 'cedar-os';

function MyComponent({ className, isActive }) {
	return (
		<div
			className={cn(
				'base-styles px-4 py-2',
				isActive && 'bg-blue-500 text-white',
				className
			)}>
			Content
		</div>
	);
}

Dark Mode Support

Cedar-OS components automatically support dark mode through Tailwind’s dark mode classes. When you toggle dark mode using toggleDarkMode(), all Cedar components will update their appearance.

Implementing Dark Mode Toggle

import { useCedarStore } from 'cedar-os';
import { Moon, Sun } from 'lucide-react';

function DarkModeToggle() {
	const { styling, toggleDarkMode } = useCedarStore();

	useEffect(() => {
		// Apply dark mode class to document
		if (styling.darkMode) {
			document.documentElement.classList.add('dark');
		} else {
			document.documentElement.classList.remove('dark');
		}
	}, [styling.darkMode]);

	return (
		<button
			onClick={toggleDarkMode}
			className='p-2 rounded-lg bg-gray-200 dark:bg-gray-800'>
			{styling.darkMode ? <Sun /> : <Moon />}
		</button>
	);
}

Best Practices

1. Configure Tailwind First: Always ensure your Tailwind configuration includes Cedar’s component paths before using Cedar components.

2. Set Colors Early: Configure your color scheme early in your app’s lifecycle, preferably in your root component:

   function App() {
   	const { setStyling } = useCedarStore();
   
   	useEffect(() => {
   		setStyling({
   			color: '#YourBrandColor',
   			secondaryColor: '#YourSecondaryColor',
   			accentColor: '#YourAccentColor',
   		});
   	}, []);
   
   	return <YourApp />;
   }
   

3. Consistent Theme: Use the styling slice to maintain consistent theming across all Cedar components rather than overriding styles individually.

4. Responsive Dark Mode: Always test your color choices in both light and dark modes to ensure good contrast and readability.

Troubleshooting

Styles Not Applying

If Cedar component styles aren’t working:

1. Check Tailwind Config: Ensure Cedar paths are included in your Tailwind configuration
2. Clear Cache: Try clearing your build cache and rebuilding
3. Check CSS Import: Make sure you’re importing your global CSS file that includes Tailwind directives
4. Verify Installation: Ensure both cedar-os and components are properly installed

Dark Mode Issues

If dark mode isn’t working:

1. Check HTML Class: Ensure the dark class is being applied to your <html> element
2. Tailwind Dark Mode: Verify your Tailwind config uses class strategy for dark mode:
   module.exports = {
   	darkMode: 'class',
   	// ... rest of config
   };
   

Next Steps

• Explore component customization for more advanced styling options
• Learn about custom message rendering to style chat messages
• Check out the Cedar Playground to see styling in action