{"id":13990790,"url":"https://github.com/GetStream/mml-react","last_synced_at":"2025-07-22T13:31:32.712Z","repository":{"id":38172614,"uuid":"188513373","full_name":"GetStream/mml-react","owner":"GetStream","description":"Message Markup Language (MML) support for React","archived":false,"fork":false,"pushed_at":"2023-02-24T16:51:16.000Z","size":27388,"stargazers_count":11,"open_issues_count":14,"forks_count":7,"subscribers_count":30,"default_branch":"develop","last_synced_at":"2024-11-01T03:06:04.867Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://getstream.github.io/mml-react","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GetStream.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-05-25T02:55:01.000Z","updated_at":"2023-09-18T01:34:32.000Z","dependencies_parsed_at":"2024-01-18T05:14:54.312Z","dependency_job_id":"753a76c9-233d-4b8b-a6ea-a887001ebabc","html_url":"https://github.com/GetStream/mml-react","commit_stats":{"total_commits":313,"total_committers":11,"mean_commits":"28.454545454545453","dds":0.5015974440894568,"last_synced_commit":"4354707db661971bc34d1c29080ac74cd8037893"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GetStream%2Fmml-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GetStream%2Fmml-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GetStream%2Fmml-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GetStream%2Fmml-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GetStream","download_url":"https://codeload.github.com/GetStream/mml-react/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227099007,"owners_count":17730691,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-09T13:03:14.980Z","updated_at":"2024-11-29T10:31:48.873Z","avatar_url":"https://github.com/GetStream.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# MML React\n\n[![NPM](https://img.shields.io/npm/v/mml-react.svg)](https://www.npmjs.com/package/mml-react)\n[![CI](https://github.com/GetStream/mml-react/workflows/CI/badge.svg)](https://github.com/GetStream/mml-react/actions)\n[![Component Reference](https://img.shields.io/badge/docs-component%20reference-blue.svg)](https://getstream.github.io/mml-react/)\n\n## Installation\n\n```bash\n// YARN\nyarn add mml-react\n\n// NPM\nnpm install mml-react --save\n\n```\n\n## Usage\n\n```jsx\nimport { MML } from 'mml-react';\n\n\u003cMML source=\"\u003cmml\u003eText\u003c/mml\u003e\" /\u003e;\n```\n\n## Overwriting Components\n\nMaking basic changes to the components is quite easy. You can use this option to add support for more custom tags.\n\nHere's an example of how to overwrite the button tag's React component:\n\n```jsx\nconst converters = {\n  button: (tag, children) =\u003e {\n    return \u003cMyCustomButton {...tag.node.attributes} text={tag.getText()} key={tag.key} /\u003e;\n  },\n};\n\n\u003cMML converters={converters} source={source} /\u003e;\n```\n\n## Components\n\nMML React components could be divided in four categories:\n\n### Naked Components\n\n\u003e Very basic pieces of UI typically beyond a matter of styling\n\n- [`Row`](src/components/Row.mdx)\n- [`Col`](src/components/Col.mdx)\n\n### Container Components\n\n\u003e Always host other components, can be themable\n\n- [`Card`](src/components/Card.mdx)\n- [`CardHeader`](src/components/CardHeader.mdx)\n- [`CardBody`](src/components/CardBody.mdx)\n\n### Core Components\n\n\u003e Basic components that can be composed and themed\n\n- [`Text`](src/components/Text.mdx): a block of text\n- [`Button`](src/components/Button.mdx): a simple button\n- [`Image`](src/components/Image.mdx): a simple responsive image\n- [`Input`](src/components/Input.mdx): an input field\n- [`MD`](src/components/MD.mdx): renders markdown\n- [`Icon`](src/components/Icon.mdx): simply displays an icon from material design icons\n- [`Loading`](src/components/Loading.mdx): signals a _loading_ temporary state with a circular spinner\n- [`Error`](src/components/Error.mdx): display an _error_ message\n- [`Success`](src/components/Success.mdx): display a _success_ message\n\n### Structured Components\n\n\u003e More complex components composed of other components, certainly themable\n\n- [`AddToCalendar`](src/components/AddToCalendar.mdx): wrapped in a [`Card`](src/components/Card.mdx)\n- [`Scheduler`](src/components/Scheduler.mdx): wrapped in a [`Card`](src/components/Card.mdx)\n- [`ButtonList`](src/components/ButtonList.mdx): a list of [`Button`](src/components/Button.mdx)\n- [`Carousel`](src/components/Carousel.mdx): a series of [`CarouselItem`](src/components/CarouselItem.mdx) typically containing [`Image`](src/components/Image.mdx), [`Text`](src/components/Text.mdx) and [`Button`](src/components/Button.mdx)\n- [`Number`](src/components/Number.mdx): input spinner composed of two [`Button`](src/components/Button.mdx) and a counter\n\n## Styles customization\n\nMML react ships with some good looking default styles but it can be completely customised to suit your visual identity.\n\n### Themes\n\nMML ships with a default theme plus four variations. These differentiate from one another only in terms of colours providing different look and feels that suits common scenarios like Social messaging, Customer support, etc. Each theme is either available in the compiled and autoprefixed `dist/styles/{name}.css` file and in the `src/styles/{name}.scss` source file. You should always include only one of this files, either `css` or `scss`, as they all includes the basic styling your MML components need.\n\nIf your projects include a `sass` compilation step you might tweak the theme variables and roll out your branded style. A theme is made of the following SCSS map:\n\n```scss\n$mml-theme: (\n  primary-accent: #006cff,\n  app-canvas: #fff,\n  text-high-emphasis: #0e1621,\n  text-mid-emphasis: #8a898e,\n  text-low-emphasis: #b2b1b5,\n  text-self: #fff,\n  text-pressed: #fff,\n  card-bg: #f2f2f2,\n  card-alt-bg: #fff,\n  card-self-bg: #41affc,\n  stroke: #e5e5e6,\n  stroke-low-emphasis: #f2f2f2,\n  shadow: 0px 2px 5px rgba(0, 0, 0, 0.15),\n);\n```\n\n\u003e If you are running `sass` within your project you might customize most aspects of mml styling other than the them through scss variables. Refer [to the source](https://github.com/GetStream/mml-react/blob/master/src/styles/common/_variables.scss) to see what is available.\n\nBy setting `$mml-use-css-vars: true` you can make each of these variables available as CSS variable that you can tweak dynamically client side, they are all prefixed with `--mml`:\n\n```css\n:root {\n  --mml-primary-accent: #006cff;\n  --mml-app-canvas: #fff;\n}\n```\n\nThe theme related data is also made available to javascript through [`icss :export`](https://github.com/css-modules/icss#export) so that you can import them and reuse them to coherently style other parts of your chat outside of MML attachments (these are used in the MML docz app for instance).\n\n```js\nimport { locals as mmlTheme } from 'mml-react/dist/styles/index.css';\n// or\nimport { locals as mmlTheme } from 'mml-react/src/styles/index.scss';\n\n// variables for js are transformed into camelCase, e.g.:\nprimaryAccent: '#006cff',\nappCanvas: '#fff',\n// ...etc.\n```\n\n### Differentiations between mine and other's messages\n\nSome components need to slightly change according to their position in the chat. To achieve this MML scope its `CSS` alterations in a configurable selector through the `SCSS` variables `$mml-selector-wrapper-align-right` and `$mml-selector-wrapper-align-left` whose default values are respectively `.mml-align-right` and `.mml-align-left` class selectors. These selectors need to be placed on the container element that wraps your MML attachment. Internally to this library these SCSS tweaks are implemented through the `SCSS mixins mml-align-right and mml-align-left`, e.g.:\n\n```scss\n@include mml-component('text') {\n  @include mml-align-left() {\n    text-align: left;\n  }\n\n  @include mml-align-right() {\n    text-align: right;\n  }\n}\n```\n\n### HTML structure\n\nMML attachments always have two wrapping elements with the following two classes:\n\n```scss\n.mml-container\n  .mml-wrap\n```\n\nThe class `.mml-container` is responsible for some very basic styling that other components inherit, like `border-box` and `font-family`.\nThe class `.mml-wrap` instead takes care of contextual styling, like `border-radius` and `margin`s, that are most likely dependent on the differentiation between _me_ and _other_ messages [seen above](#differentiations-between-mine-and-others-messages).\n\nInside `mml-wrap` you could have as immediate children either the components as they are or the components automatically wrapped in a `\u003cdiv class=\"mml-card\"\u003e...\u003c/div\u003e` when `\u003cmml type=\"card\"\u003e` is used (see the [`MML` docs](src/mml/MML.mdx#with-card-type)). Note that the `mml-card` class (and its `Card` React component) is also used internally in various components like [`Scheduler`](src/components/Scheduler.mdx) and [`AddToCalendar`](src/components/AddToCalendar.mdx).\n\n## Development \u0026 Contributions\n\n## commands\n\n- `yarn docs` to run hot reload docs, best way to work on the components\n- `yarn build` to build and type check\n- `yarn lint` to run linting\n- `yarn format` to prettify things\n- `yarn test` to run tests\n- `npm version patch|minor|major` to make a release\n\n## Understanding the Parser\n\n1. SourceToXML parse MML string into XML node structure\n2. XMLtoMMLTree converts the XML nodes to a tree of MML nodes (MMLTree)\n3. MMLTree can be converted to React nodes using ToReact method\n\n## Tree\n\nThe tree has:\n\n- The name of the MML tag (passed to callback data as `mml_name`)\n- MMLTag Children\n\n## Naming\n\n- Tree: The tree of MML tags\n- Converters: Mapping from MMLTag to React Component\n\n## How to create a new tag\n\nLet's say you want to create a new tag called `color_picker`.\nHere's how you would go about implementing it.\n\n### Step 1 - React node\n\nIn `src/components` directory create a file called `ColorPicker.tsx` and do something along these lines:\n\n```jsx\nexport const ColorPicker: FC\u003cColorPickerProps\u003e = ({ name, value = '' }) =\u003e {\n  const [state, setState] = useState(value);\n  return (\n    \u003cinput\n      className=\"mml-input\"\n      name={name}\n      value={state}\n      placeholder={placeholder}\n      onChange={(event) =\u003e setState(event.target.value)}\n    /\u003e\n  );\n};\n```\n\n### Step 2 - Converters\n\nAdd an entry to `converters.tsx` file\n\n```jsx\ncolor_picker: (tag: MMLTag) =\u003e {\n  return \u003cColorPicker {...tag.attributes} key={tag.key} name={tag.attributes.name} value={tag.attributes.value} /\u003e;\n};\n```\n\n### Step 3 - Doc\n\nDocs is the easiest way to test your component in isolation. Simply create a new file named `ColorPicker.mdx` similar to other mdx files in the component directory and document/test the component.\n\n## Contributing\n\nWe welcome code changes that improve this library or fix a problem. Please make sure to follow all best practices and add tests if applicable before submitting a Pull Request on Github. We are pleased to merge your code into the official repository. Make sure to sign our [Contributor License Agreement (CLA)](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform) first. See our license file for more details.\n\n## We are hiring!\n\nWe've recently closed a [$38 million Series B funding round](https://techcrunch.com/2021/03/04/stream-raises-38m-as-its-chat-and-activity-feed-apis-power-communications-for-1b-users/) and we keep actively growing.\nOur APIs are used by more than a billion end-users, and you'll have a chance to make a huge impact on the product within a team of the strongest engineers all over the world.\n\nCheck out our current openings and apply via [Stream's website](https://getstream.io/team/#jobs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGetStream%2Fmml-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGetStream%2Fmml-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGetStream%2Fmml-react/lists"}