\n\n> Currently, this package is under development. You can follow the progress [here](https://github.com/arikchakma/maily.to).\n\n## Installation\n\n```bash\npnpm add @maily-to/core\n\n# for types\npnpm add -D @tiptap/core\n```\n\n## Usage\n\n```tsx\nimport '@maily-to/core/style.css';\n\nimport { useState } from 'react';\nimport { Editor } from '@maily-to/core';\nimport type { Editor as TiptapEditor, JSONContent } from '@tiptap/core';\n\ntype AppProps = {\n contentJson: JSONContent;\n};\n\nfunction App(props: AppProps) {\n const { contentJson: defaultContentJson } = props;\n const [editor, setEditor] = useState();\n\n return (\n \n );\n}\n```\n\n### Slash Commands\n\nSlash commands let you interact with the editor by typing `/` followed by a command name. Commands are now organized into groups. Each group is an object with a `title` and a `commands` array. Every command within that array is a `BlockItem` that can either be a single command or a grouped command (with commands).\n\n#### Basic Example\n\nSuppose you have a couple of basic blocks, such as a text block or a heading block. You would organize them into a group like this:\n\n```tsx\n// omitting imports\nimport { text, heading1 } from '@maily-to/core/blocks';\n\n\n```\n\n> **Note:** The order of the groups and the order of commands within each group determine how they are displayed in the editor.\n\n#### Grouped Command Blocks with Subcommands\n\nSometimes, you may want a single command to open a list of commands. For this, define a command with an `id` and a `commands` array. The `id` is used for the slash command query (for example, typing `/headers.` will show its subcommands).\n\n```tsx\n// omitting imports\n {\n // Convert the current block to Heading 1.\n },\n },\n {\n title: 'Heading 2',\n searchTerms: ['h2', 'heading2'],\n command: ({ editor, range }) => {\n // Convert the current block to Heading 2.\n },\n },\n // Add more subcommands as needed.\n ],\n },\n ],\n },\n ]}\n/>\n```\n\nIn this setup, when the user types `/headers.`, the editor will display the available header subcommands.\n\n> **Note:** Currently it only supports one level of depth for subcommands.\n\n#### Custom Rendered Blocks\n\nTo render a custom block, you can pass a `render` function to the block object. The `render` function will receive the editor instance as an argument. You can return `null` if you don't want to render anything based on the editor's state.\n\n```tsx\n// omitting imports\n {\n return
Custom Block
;\n },\n },\n ],\n },\n ]}\n/>\n```\n\n### Variables\n\nBy default, variables are required. You can make them optional by setting the `required` property to `false`. When a variable is optional and not provided, a placeholder will be displayed in its place.\n\nYou can pass variables to the editor in two ways:\n\n1. As an Array of Objects:\n\n For auto-suggestions of variables in the editor when you type `@`, pass the variables as an array of objects to the `variables` prop.\n\n ```tsx\n // (Omitted repeated imports)\n import { VariableExtension, getVariableSuggestions } from '@maily-to/core/extensions';\n\n \n ```\n\n2. As a Function:\n\n If the variables are dynamic and need to be generated based on the editor's state or other inputs, you can provide a function to the `variables` prop.\n\n ```tsx\n // (Omitted repeated imports)\n import { VariableExtension, getVariableSuggestions } from '@maily-to/core/extensions';\n\n {\n // magic goes here\n // query: the text after the trigger character\n // from: the context from where the variables are requested (repeat, variable)\n // editor: the editor instance\n if (from === 'repeat-variable') {\n // return variables for the Repeat block `each` key\n return [\n { name: 'notifications' },\n { name: 'comments' },\n ];\n }\n\n return [\n { name: 'currentDate' },\n { name: 'currentTime', required: false },\n {\n name: 'first_name',\n required: false,\n // if you want to hide the default value\n // input in the popover\n hideDefaultValue: true,\n },\n ];\n },\n }),\n ]}\n />\n ```\n\n> Keep it in mind that if you pass an array of variable object Maily will take care of the filtering based on the query. But if you pass a function you have to take care of the filtering.\n\n### Extensions\n\nExtensions are a way to extend the editor's functionality. You can add custom blocks, marks, or extend the editor's functionality using extensions.\n\n```tsx\n// (Omitted repeated imports)\nimport { MailyKit, VariableExtension, getVariableSuggestions } from '@maily-to/core/extensions';\n\n\n```\n\nOr, you can add your own custom extensions, like shown below:\n\n```tsx\n// (Omitted repeated imports)\nimport { CustomExtension } from './extensions/custom-extension';\n\n\n```\n\n### Image Upload\n\nTo enable image upload, you need to pass the `ImageUploadExtension` extension to the editor. The `onImageUpload` function will be called when an image is being uploaded. You can use this function to upload the image to your server and return the URL.\n\n```tsx\n// (Omitted repeated imports)\nimport { ImageUploadExtension } from '@maily-to/core/extensions';\n\n {\n // upload the image to wherever you want\n const url = await uploadImage(file);\n return url;\n },\n }),\n ]}\n/>\n```\n\nSee the [@maily-to/render](../render) package for more information on how to render the editor content to HTML.\n\n \n\n## Sponsors\n\nSponsorship at any level is appreciated and encouraged. If you built a paid product using Maily, consider one of the [sponsorship tiers](https://github.com/sponsors/arikchakma).\n\n \n\n
![](\"https://maily.to/brand/icon.svg\"){kind=icon}
![](\"https://img.shields.io/badge/License-MIT-222222.svg\"){kind=icon}
\n ![\"Get](\"https://img.shields.io/badge/%E2%9C%A8-Get%20Editor-0a0a0a.svg?style=flat&colorA=0a0a0a\"){kind=icon}
\n