How to Embed Twitter/X Tweets in Editor Content with reactjs-tiptap-editor

The reactjs-tiptap-editor provides a dedicated Twitter extension that converts tweet URLs into embedded nodes using the setTweet command, renders them via react-tweet, and supports automatic conversion through paste rules.

Embedding social media content directly into rich-text documents requires a specialized node architecture. The hunghg255/reactjs-tiptap-editor repository implements this through a custom Twitter node extension that handles URL validation, command registration, and React-based rendering. This solution allows users to embed Twitter/X tweets by pasting URLs or using toolbar controls, with the editor automatically extracting tweet IDs and displaying interactive embeds.

Architecture of the Twitter Extension

The embedding functionality follows the standard Tiptap pattern of separating node definitions from view components. This architecture ensures that tweet nodes behave like native editor elements while maintaining isolated rendering logic.

Node Definition and Commands

In src/extensions/Twitter/Twitter.ts, the extension defines a custom Node that stores the tweet URL in a src attribute. The implementation registers two primary commands:

• setTweet – Inserts a new tweet node at the current cursor position
• updateTweet – Modifies the URL of an existing tweet node

The node also configures a paste rule using nodePasteRule that automatically transforms matching URLs into tweet nodes when users paste content. This rule relies on the TWITTER_REGEX_GLOBAL pattern to validate URLs matching https://x.com/<username>/status/<tweetId> or http://x.com/... formats.

React Node View Rendering

When the editor renders a tweet node, it delegates to ReactNodeViewRenderer configured in Twitter.ts. This loads the NodeViewTweet component from src/extensions/Twitter/components/NodeViewTweet.tsx.

NodeViewTweet performs two critical functions:

1. URL Parsing – Extracts the tweet ID from the stored src attribute using the shared TWITTER_REGEX
2. Component Rendering – Passes the extracted ID to the <Tweet> component from the react-tweet library, which handles the actual embed display and styling

Toolbar Integration and UI Controls

The toolbar interface resides in src/extensions/Twitter/components/RichTextTwitter.tsx. This component provides:

• A toolbar button that triggers a pop-over interface
• FormEditLinkTwitter – A form component where users input or edit tweet URLs
• Command invocation that calls setTweet or updateTweet based on whether the cursor is inside an existing tweet node

The UI validates URLs before submission, ensuring only valid X.com or Twitter.com status URLs are accepted.

Step-by-Step Implementation

To enable tweet embedding in your editor instance, you must register the extension and include the toolbar component.

Registering the Twitter Extension

Import the Twitter extension and RichTextTwitter toolbar component, then add them to your editor configuration:

import { RichTextProvider } from 'reactjs-tiptap-editor';
import {
  Document,
  Text,
  Paragraph,
  Dropcursor,
  Gapcursor,
  Placeholder,
  TrailingNode,
  HardBreak,
  ListItem,
  TextStyle,
} from '@tiptap/extension-...'; // base extensions
import { Twitter, RichTextTwitter } from 'reactjs-tiptap-editor/twitter';
import 'reactjs-tiptap-editor/style.css';

const extensions = [
  Document,
  Text,
  Paragraph,
  Dropcursor,
  Gapcursor,
  HardBreak,
  ListItem,
  TextStyle,
  Placeholder.configure({ placeholder: "Press '/' for commands" }),
  TrailingNode,
  // … other extensions you need
  Twitter,               // ← enable tweet nodes
];

function App() {
  const editor = useEditor({ extensions });

  return (
    <RichTextProvider editor={editor}>
      {/* Toolbar */}
      <RichTextTwitter />
      {/* Editor area */}
      <EditorContent editor={editor} />
    </RichTextProvider>
  );
}

See the full implementation details in the documentation at docs/extensions/Twitter/index.md.

Inserting Tweets Programmatically

You can insert tweets via the setTweet command by providing a valid tweet URL:

// Example: Custom button or menu action
function insertTweet() {
  editor.commands.setTweet({
    src: 'https://x.com/nextjs/status/1234567890123456789',
  });
}

If the URL fails regex validation, setTweet returns false and no node is created.

Updating Existing Tweet Nodes

To modify a tweet URL when the cursor is inside an existing tweet node:

editor.commands.updateTweet({
  src: 'https://x.com/nextjs/status/9876543210987654321',
});

Handling Paste Events

With addPasteHandler enabled (the default), users can simply paste a tweet URL directly into the editor. The paste rule defined in Twitter.ts automatically converts valid URLs:

// Implementation detail from Twitter.ts
nodePasteRule({
  find: TWITTER_REGEX_GLOBAL,
  type: this.type,
  getAttributes: (match) => ({ src: match.input }),
});

No additional code is required to support this functionality; it activates automatically when the extension is registered.

Configuration and Validation

The extension validates all URLs against TWITTER_REGEX before processing. This regex specifically matches:

• https://x.com/{username}/status/{tweetId}
• http://x.com/{username}/status/{tweetId}

Invalid URLs are ignored during paste operations and rejected by the setTweet command. To disable automatic paste conversion, you would need to modify the extension configuration, though the default behavior suits most use cases.

Summary

• Node Architecture – The Twitter extension in src/extensions/Twitter/Twitter.ts defines a custom node with src attributes and registers setTweet and updateTweet commands.
• React Rendering – NodeViewTweet.tsx uses react-tweet to render interactive embeds, extracting tweet IDs from validated URLs.
• Toolbar Integration – RichTextTwitter.tsx provides the UI for manual URL insertion and editing through a pop-over form.
• Automatic Conversion – Paste rules automatically convert matching X.com URLs into embedded tweets without requiring toolbar interaction.
• Validation – All URLs must match the TWITTER_REGEX pattern to ensure only valid status links are embedded.

Frequently Asked Questions

What URL formats does the Twitter extension support?

The extension supports standard X.com and Twitter.com status URLs in the format https://x.com/username/status/tweetID. The validation regex in Twitter.ts specifically checks for this pattern, and both HTTP and HTTPS protocols are accepted. URLs containing query parameters or fragments may not match the regex and will be rejected.

Can I disable automatic paste conversion for tweets?

Yes, the paste handling is controlled by the addPasteHandler option in the extension configuration. While the default is true, you can disable automatic conversion by configuring the extension with addPasteHandler: false, requiring users to use the toolbar button (RichTextTwitter) to insert tweets manually.

How does the editor render the actual tweet content?

The editor uses the react-tweet library through the NodeViewTweet component. When a tweet node is rendered, NodeViewTweet extracts the tweet ID from the stored URL and passes it to the <Tweet> component from react-tweet. This library handles fetching the tweet data and rendering the interactive embed, including media and engagement metrics, directly within the editor canvas.

What happens if I provide an invalid Twitter URL to setTweet?

The setTweet command validates the input URL against TWITTER_REGEX before insertion. If the URL does not match the expected pattern (e.g., missing the status ID or using an unsupported domain), the command returns false and no tweet node is created. This prevents broken embeds from entering the document state.

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