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

> Learn how to use the Raw component in reacticle to embed custom HTML CSS and JavaScript directly into your articles using dangerouslySetInnerHTML for powerful customization.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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:

```tsx
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`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/assets/scaffold-template/article/sections/01-opening.tsx), the component demonstrates token-driven SVG styling:

```tsx
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:

```tsx
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`](https://github.com/ConardLi/garden-skills/blob/main/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:

```tsx
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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/raw-policy.md) guidelines—this approach provides the flexibility needed for complex custom markup.