# @wix/ricos

Ricos is the Rich Content solution for Wix — used both internally and in headless environments. It provides three core building blocks that can be used together or independently:

- **RicosEditor** — a full-featured WYSIWYG editor with an extensible plugin system
- **RicosViewer** — a read-only renderer for displaying rich content
- **RicosDocument** — the content data model (JSON) that flows between editor and viewer.

<svg viewBox="0 0 620 260" xmlns="http://www.w3.org/2000/svg" style="max-width:620px;margin:24px auto;display:block">
  <style>
    .box { fill: #f8fafc; stroke: #94a3b8; stroke-width: 2; rx: 12; }
    .ellipse { fill: #f8fafc; stroke: #94a3b8; stroke-width: 2; }
    .label { font-family: ui-monospace, monospace; font-size: 18px; fill: #1e293b; text-anchor: middle; dominant-baseline: central; }
    .arrow { fill: none; stroke: #94a3b8; stroke-width: 1.5; marker-end: url(#arrowhead); }
  </style>
  <defs><marker id="arrowhead" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#94a3b8"/></marker></defs>
  <rect class="box" x="20" y="120" width="200" height="100"/>
  <text class="label" x="120" y="170">RicosEditor</text>
  <rect class="box" x="400" y="120" width="200" height="100"/>
  <text class="label" x="500" y="170">RicosViewer</text>
  <ellipse class="ellipse" cx="310" cy="55" rx="120" ry="40"/>
  <text class="label" x="310" y="55">RicosDocument</text>
  <line class="arrow" x1="200" y1="130" x2="260" y2="85"/>
  <line class="arrow" x1="270" y1="95" x2="215" y2="135"/>
  <line class="arrow" x1="350" y1="85" x2="420" y2="130"/>
</svg>

```bash
npm i @wix/ricos
```

All three are exported from `@wix/ricos`:

```tsx
import { RicosEditor, RicosViewer, type RicosDocument } from '@wix/ricos';
```

## Quick Start

### Viewer

```tsx widget
import '@wix/ricos/css/plugin-image-viewer.global.css';
import '@wix/ricos/css/ricos-viewer.global.css';
import type { RicosDocument } from '@wix/ricos';
import { pluginImageViewer, RicosViewer } from '@wix/ricos';
import React from 'react';

export default () => {
  // @essential-start
  return <RicosViewer content={content} plugins={[pluginImageViewer()]} />;
  // @essential-end
};

const content: RicosDocument = {
  nodes: [
    {
      type: 'PARAGRAPH',
      id: 'p1',
      nodes: [
        {
          type: 'TEXT',
          id: '',
          nodes: [],
          textData: { text: 'A read-only Ricos document with an image:', decorations: [] },
        },
      ],
    },
    {
      type: 'IMAGE',
      id: 'img1',
      nodes: [],
      imageData: {
        containerData: {
          width: { size: 'CONTENT' },
          alignment: 'CENTER',
          textWrap: true,
        },
        image: {
          src: { url: 'https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885_1280.jpg' },
          width: 5120,
          height: 3413,
        },
        altText: 'A tree during sunset.',
      },
    },
  ],
};
```

### Editor

```tsx widget
import type { RicosDocument, RicosEditorType } from '@wix/ricos';
import { pluginImage, RicosEditor } from '@wix/ricos';
import React from 'react';

export default () => {
  const editorRef = React.useRef<RicosEditorType>(null);

  // oxlint-disable-next-line no-alert
  const handlePublish = async () => {
    // @essential-start
    const document = await editorRef.current?.prePublish();
    alert(`Publishing ${document?.nodes.length ?? 0} nodes`);
    // @essential-end
  };

  return (
    // @essential-start
    <>
      <RicosEditor
        ref={editorRef}
        initialContent={initialContent}
        plugins={[pluginImage()]}
        placeholder={'Edit me — drag an image in or use the toolbar'}
      />
      <button onClick={handlePublish} type="button">
        Publish
      </button>
    </>
    // @essential-end
  );
};

const initialContent: RicosDocument = {
  nodes: [
    {
      type: 'PARAGRAPH',
      id: 'p1',
      nodes: [
        {
          type: 'TEXT',
          id: '',
          nodes: [],
          textData: { text: 'An editable Ricos document with an image.', decorations: [] },
        },
      ],
    },
    {
      type: 'IMAGE',
      id: 'img1',
      nodes: [],
      imageData: {
        containerData: {
          width: { size: 'CONTENT' },
          alignment: 'CENTER',
          textWrap: true,
        },
        image: {
          src: { url: 'https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885_1280.jpg' },
          width: 5120,
          height: 3413,
        },
        altText: 'A tree during sunset.',
      },
    },
  ],
};
```

