How to Use the Raw Component in Reacticle for Custom HTML, CSS, and JavaScript

The Raw component in reacticle allows you to embed arbitrary HTML, CSS, JavaScript, or React components directly into Beautiful Articles by rendering children as React elements or injecting raw HTML strings via dangerouslySetInnerHTML.

The reacticle UI library provides the Raw component as an escape hatch for authors who need to step outside the standard article grammar. Whether you need inline SVG graphics, CSS animations, or interactive JavaScript widgets, understanding how to use the Raw component in reacticle gives you full web platform freedom while maintaining theme consistency. This guide covers the implementation patterns and policies defined in the ConardLi/garden-skills repository.

What Is the Raw Component?

The Raw component serves as the only sanctioned location where you can break free from the structured "Section / Aside / Quote" grammar of Beautiful Articles. Located within the reacticle UI library, this component accepts either React children or raw HTML strings and renders them as-is in the final article output.

All markup processed by Raw respects the article's active theme, allowing custom blocks to adapt automatically when readers switch between light and dark modes. This is achieved through CSS custom properties—theme tokens prefixed with --ra-—that propagate into your custom HTML and CSS.

Importing Raw from Reacticle

Before implementing custom content, import the component from the reacticle package:

import { Raw } from "reacticle";

The component is typically used within section files, such as those found in skills/beautiful-article/assets/scaffold-template/article/sections/. Each Raw instance should reside inside a Section or similar layout container to maintain proper article structure.

How to Use Raw: Three Implementation Patterns

The Raw component supports two primary content delivery modes: React children for component-based markup, and the html prop for raw string injection. An optional title prop provides accessibility labels and debugging context without affecting rendering.

Rendering React Children (Inline SVG)

When you pass JSX elements as children, Raw renders them as standard React components. This pattern is ideal for inline SVG graphics or lightweight JSX structures that leverage theme tokens.

In skills/beautiful-article/assets/scaffold-template/article/sections/01-opening.tsx, the component demonstrates token-driven SVG styling:

import { Section, Raw } from "reacticle";

export function SvgDemo() {
  return (
    <Section index="02" title="SVG Demo">
      <Raw title="Inline SVG illustrating a trend">
        <svg viewBox="0 0 240 60" width="100%">
          <polyline
            points="0,50 40,42 80,46 120,20 160,28 200,8 240,14"
            fill="none"
            stroke="var(--ra-color-accent)"
            strokeWidth="2"
          />
        </svg>
      </Raw>
    </Section>
  );
}

Notice the use of var(--ra-color-accent) instead of hardcoded colors. This ensures the SVG automatically adapts to the article's color theme.

Injecting Raw HTML Strings (CSS/JS Animation)

For quick snippets that combine HTML, CSS, and JavaScript without creating separate components, pass a string to the html prop. The component internally applies this via dangerouslySetInnerHTML, making this approach suitable for legacy markup or complex CSS keyframe animations:

import { Section, Raw } from "reacticle";

export function CssAnimationDemo() {
  return (
    <Section index="03" title="CSS Animation Demo">
      <Raw
        title="CSS keyframe animation"
        html={`
          <style>
            @keyframes ra-rise {
              from { height: 0; }
              to   { height: var(--h); }
            }
          </style>
          <div style="display:flex;gap:8px;align-items:flex-end;height:80px">
            <i style="--h:60%;flex:1;background:var(--ra-color-accent);animation:ra-rise .6s ease"></i>
            <i style="--h:90%;flex:1;background:var(--ra-color-accent);animation:ra-rise .8s ease"></i>
          </div>
        `}
      />
    </Section>
  );
}

This pattern, documented in skills/beautiful-article/references/raw-policy.md, allows inline style definitions while maintaining access to theme tokens through CSS variables.

Embedding Custom React Components

For interactive JavaScript functionality, define a local React component and pass it as a child to Raw. This maintains type safety and React lifecycle management while still rendering within the raw content boundary:

import { Section, Raw } from "reacticle";
import { useState } from "react";

function TokenScale() {
  const [n, setN] = useState(50);
  return (
    <div>
      <input 
        type="range" 
        value={n} 
        onChange={e => setN(+e.target.value)} 
      />
      <span style={{ color: "var(--ra-color-accent)" }}>
        {n}%
      </span>
    </div>
  );
}

export function InteractiveDemo() {
  return (
    <Section index="04" title="Interactive Demo">
      <Raw title="Adjustable token scale">
        <TokenScale />
      </Raw>
    </Section>
  );
}

Styling with Theme Tokens

Every Raw implementation should respect the token-driven styling policy defined in raw-policy.md. Theme tokens follow the pattern var(--ra-*) and cover:

• Colors: var(--ra-color-accent), var(--ra-color-text-primary)
• Typography: var(--ra-font-body), var(--ra-font-heading)
• Spacing: var(--ra-space-4), var(--ra-space-8)

Hardcoding hex codes or pixel values violates the theme contract and causes visual inconsistency when readers switch themes.

Raw Component Props Reference

Prop	Type	Required	Description
children	ReactNode	No	React elements rendered as-is via standard React rendering
html	string	No	Raw HTML string injected via dangerouslySetInnerHTML
title	string	No	Accessibility label and debugging identifier

You cannot use both children and html simultaneously. Choose the pattern that best fits your content type.

Best Practices and Policy Guidelines

The ConardLi/garden-skills repository enforces strict policies for Raw usage via skills/beautiful-article/references/raw-policy.md. Follow this checklist before committing:

1. Essential contribution: The block must add necessary understanding that structured components cannot provide
2. Token compliance: Verify all colors, fonts, and spacing use var(--ra-*) tokens
3. One-off design: Write markup for the specific section; avoid creating reusable widgets that appear across multiple sections
4. Performance limits: Exclude heavy libraries, complex dashboards, or independent animations unrelated to the narrative

Summary

• The Raw component is the escape hatch for embedding custom HTML, CSS, and JavaScript in reacticle articles
• Import from reacticle and use either children (React components) or the html prop (string injection)
• Always apply theme tokens (var(--ra-*)) to ensure visual consistency across themes
• Reference the source examples in skills/beautiful-article/assets/scaffold-template/article/sections/ for implementation patterns
• Adhere to the one-off and lightweight policies specified in raw-policy.md

Frequently Asked Questions

Can I use both children and the html prop in the same Raw component?

No, the Raw component accepts either React children or an html string, but not both simultaneously. Choose children when you need React lifecycle methods and type safety, or use the html prop for quick markup fragments that combine HTML, CSS, and JavaScript without component overhead.

How do I make sure my custom CSS works with the article's theme?

Reference theme tokens using CSS custom properties like var(--ra-color-accent) and var(--ra-font-body) instead of hardcoding values. These tokens dynamically resolve to the current theme's values, ensuring your custom block adapts automatically when the article theme changes between light and dark modes.

Where should I place Raw components within my article structure?

Always place Raw components inside Section containers or other layout components from reacticle. The component is designed to live within the article's semantic structure—typically defined in files like skills/beautiful-article/assets/scaffold-template/article/sections/02-example.tsx—rather than at the root level.

Is it safe to use dangerouslySetInnerHTML with the html prop?

While Raw uses dangerouslySetInnerHTML internally when you provide the html prop, it is safe when you control the input content. Never pass user-generated or untrusted content to the html prop. For static, author-controlled HTML/CSS/JS snippets—as documented in the raw-policy.md guidelines—this approach provides the flexibility needed for complex custom markup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}