Val

React Components

Val provides React components to help you render Val content in your application. These components are optimized for Val's content types and handle visual editing integration automatically.

ValRichText

The ValRichText component renders Val's rich text content with customizable styling. It converts Val's rich text structure into properly formatted HTML while maintaining visual editing capabilities.

Props

content (required) - The Val rich text content to render
theme (optional) - CSS classes for styling rich text elements. If provided, you must style all enabled features from your schema.

Basic usage

import { ValRichText } from "@valbuild/next/client";
import { fetchVal } from "@/val/val.rsc";
import articleVal from "./article.val";

export default async function Article() {
  const { content } = await fetchVal(articleVal);
  
  return <ValRichText content={content} />;
}

With custom theme

The theme object uses CSS classes (like Tailwind) to style each rich text feature. TypeScript ensures you provide styling for all features enabled in your schema:

import { ValRichText } from "@valbuild/next/client";

export default async function Article() {
  const { content } = await fetchVal(articleVal);
  
  return (
    <ValRichText
      content={content}
      theme={{
        bold: "font-bold",
        italic: "italic",
        underline: "underline",
        lineThrough: "line-through",
        h1: "text-4xl font-bold mb-4",
        h2: "text-3xl font-bold mb-3",
        h3: "text-2xl font-bold mb-2",
        p: "mb-4",
        ul: "list-disc pl-6 mb-4",
        ol: "list-decimal pl-6 mb-4",
        blockquote: "border-l-4 pl-4 italic my-4",
        a: "text-blue-600 hover:underline",
      }}
    />
  );
}

Type Safety

The theme prop is type-checked based on your rich text schema. If you enable bold and italic in your schema, the theme must include styling for both. This prevents missing styles when you extend your rich text capabilities.

ValImage

The ValImage component is a wrapper around Next.js's optimized Image component that works seamlessly with Val image content. It automatically extracts image metadata (width, height, alt text) and provides proper optimization.

Props

src (required) - The Val image object from your content
All other Next.js Image props - className, priority, loading, etc.

Basic usage

import { ValImage } from "@valbuild/next/client";
import { fetchVal } from "@/val/val.rsc";
import pageVal from "./page.val";

export default async function Page() {
  const { hero } = await fetchVal(pageVal);
  
  return <ValImage src={hero} />;
}

With Next.js Image props

You can pass all standard Next.js Image component props to customize image rendering:

import { ValImage } from "@valbuild/next/client";

export default async function Page() {
  const { hero, thumbnail } = await fetchVal(pageVal);
  
  return (
    <div>
      {/* Hero image with priority loading */}
      <ValImage 
        src={hero} 
        priority
        className="w-full h-auto"
      />
      
      {/* Thumbnail with custom styling */}
      <ValImage 
        src={thumbnail}
        className="w-32 h-32 object-cover rounded-lg"
        loading="lazy"
      />
    </div>
  );
}

Why use ValImage?

While you can use Next.js Image directly with image.url, ValImage provides several benefits:

Automatically extracts and uses image metadata (width, height, alt)
Handles visual editing attributes for click-to-edit functionality
Uses hotspot automatically
Works seamlessly with both local and remote images

ValProvider

The ValProvider component is a React context provider that enables Val functionality throughout your application. This component is typically set up once during project initialization and rarely needs to be modified.

Props

config (required) - The configuration object from initVal
children (required) - Your application components

Setup in root layout

The ValProvider is typically added to your root layout file during initial Val setup. This was likely done automatically if you used the Val initialization script:

import { ValProvider } from "@valbuild/next/client";
import { config } from "@/val.config";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <ValProvider config={config}>
          {children}
        </ValProvider>
      </body>
    </html>
  );
}

When do I need this?

You only need to interact with ValProvider during initial project setup. If you used npm create @valbuild or the Val initialization script, this is already configured for you. You won't need to modify it unless you're integrating Val into an existing project manually.