{"id":22636742,"url":"https://github.com/kgram/react-equation","last_synced_at":"2025-04-11T21:21:23.269Z","repository":{"id":19194209,"uuid":"86471353","full_name":"kgram/react-equation","owner":"kgram","description":"A parser, resolver and renderer for equations in react","archived":false,"fork":false,"pushed_at":"2024-01-16T09:21:21.000Z","size":6070,"stargazers_count":43,"open_issues_count":17,"forks_count":13,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-15T07:26:52.783Z","etag":null,"topics":["equation-solver","math","react"],"latest_commit_sha":null,"homepage":"https://kgram.github.io/react-equation/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kgram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-28T14:41:38.000Z","updated_at":"2024-06-18T22:53:39.927Z","dependencies_parsed_at":"2024-06-18T22:53:00.871Z","dependency_job_id":"a34dde41-f375-4201-97aa-b93cd3fcd478","html_url":"https://github.com/kgram/react-equation","commit_stats":{"total_commits":252,"total_committers":3,"mean_commits":84.0,"dds":0.04761904761904767,"last_synced_commit":"3dbe1cbc18695c1fe9efb30a7fa6a960aaf719fb"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgram%2Freact-equation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgram%2Freact-equation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgram%2Freact-equation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgram%2Freact-equation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kgram","download_url":"https://codeload.github.com/kgram/react-equation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248480421,"owners_count":21110939,"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":["equation-solver","math","react"],"created_at":"2024-12-09T03:30:03.162Z","updated_at":"2025-04-11T21:21:23.242Z","avatar_url":"https://github.com/kgram.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `react-equation` – Parse, evaluate and render equation from plain text\n\nA react render-layer for [`equation-parser`](https://github.com/kgram/equation-parser) and [`equation-resolver`](https://github.com/kgram/equation-resolver).\n\n\n## Quick-start\nInstall the package.\n\n```\nnpm install -S react-equation equation-resolver\n```\nor\n```\nyarn add react-equation equation-resolver\n```\n\nStart rendering equations\n\n```jsx\nimport React from 'react'\nimport ReactDOM from 'react-dom'\nimport { Equation, EquationEvaluate, EquationContext, EquationOptions, defaultErrorHandler } from 'react-equation'\nimport { defaultVariables, defaultFunctions } from 'equation-resolver'\n\nReactDOM.render((\n    \u003c\u003e\n        \u003cEquationOptions\n            variables={defaultVariables}\n            functions={defaultFunctions}\n            errorHandler={defaultErrorHandler}\n        \u003e\n            \u003cEquationEvaluate\n                value='5m + 1/2m * sin(π) + (22 m^2) / (2m)'\n            /\u003e\n            \u003cEquationContext\n                render={(equation) =\u003e (\n                    \u003cp\u003e\n                        Here, we define that {equation('a = 5')}, and can then evaluate that {equation('7 / a = ')}\n                    \u003c/p\u003e\n                )}\n            /\u003e\n        \u003c/EquationOptions\u003e\n    \u003c/\u003e\n), document.getElementById(\"root\"));\n```\n\nSome more example can be seen in this sandbox: https://codesandbox.io/s/react-equation-example-t0oe8\n\nA simple playground built around `EquationContext` can be found here: https://codesandbox.io/s/react-equation-playground-w5q2en\n\n## Introduction\n\nThis package is intended to render text-equations For help with equation structure, see [`equation-parser`](https://github.com/kgram/equation-parser#general-format).\n\n### Equations in context\nThe most straight-forward way to render equations is to use the [`EquationContext`](#equationcontext) component. This component is made to render a series of interconnected equations and functions, evaluated in order, and will generally try to figure out what you want based on the form of the equation.\n\nThe `equation`-function provided to the `render`-prop allows you to render simple expressions, but also supports more complex patterns through a (hopefully) intuitive syntax:\n\n* Evaluate an expression: By ending the equation with equals and optionally a placeholder (`_`) and unit, the evaluated result is shown.\n    * `5 * 2 =`\n    * `22/7=_`\n    * `0.2m * 0.7m = _ cm^2`\n* Assign a variable: By following a variable name with equals, the value will be available as a variable in all subsequent calls to `equation`. This can be combined with the evaluate-rules above to show the value of the variable.\n    * `a = 5`\n    * `b = 2a =`\n    * `c = (100% + 2%)^3 = _ %`\n* Assign a function: Assigning a function-call where every argument is a variable-name will make it available as a function for subsequent calls to `equation`. The function can use variables and functions as defined when it itself is defined.\n\nIf you need variables or functions defined without them being shown, you can simply call `equation` without using the return value.\n\n### Direct rendered components\nIf you don't need context, or need more control over the components or bundling, you can use components directly. A component will only include the parser and evaluator when necessary, enabling efficient tree-shaking in simple scenarios.\n\n### Variables and functions\nIt is necessary to manually include variables and functions. This is to allow changing the names for localization purposes, and omitting unnecessary code for bundle optimization.\n\nThe functions included can be found in [`equation-resolver`](https://github.com/kgram/equation-resolver#defaultfunctions). There is special rendering for `sqrt`, `root`, `abs` and `sum`.\n\nThe variables are only listed [in the raw source](https://github.com/kgram/equation-resolver/blob/master/src/defaultVariables.ts), since there's quite a few of them. They should hopefully cover anything one could want to define, but if something is missing or wrong, please create an issue.\n\n## Components\nAll the included components are split up in the interest of allowing tree-shaking to reduce the bundle-size by avoiding either the parser, the resolver or both, depending on needs.\n\nAll the components can (when applicable) have props `variables`, `functions`, `simplifyableUnits` (see [`equation-resolver`](https://github.com/kgram/equation-resolver)), `errorHandler` (see section on error handling), `className` and `style`. These props can also be passed along through the `EquationOptions` context-provider.\n\n### `Equation`\nParse the string provided as `value` and render it. No evaluation is done.\n\nExposes as ref:\n\n```ts\ntype RefValue = {\n    /** Equation is valid */\n    valid: boolean,\n    /** Parsed equation */\n    equation: EquationNode | EquationParserError,\n}\n```\n\nExample:\n\n```jsx\n\u003cEquation\n    value='2 + a'\n/\u003e\n// Renders a prettified 2 + a\n```\n\n### `EquationEvaluate`\nParse the string provided as `value`, evaluate it and render the formatted equation.\n\nExposes as ref:\n\n```ts\ntype RefValue = {\n    /** Equation and result valid */\n    valid: boolean,\n    /** Parsed equation */\n    equation: EquationNode | EquationParserError,\n    /** Parsed equation for the display unit */\n    unitEquation: EquationNode | EquationParserError | null,\n    /** Evaluated result of the equation */\n    result: ResultNode | ResultResolveError,\n    /** Evaluated result of the unit passed */\n    unitResult: ResultNode | ResultResolveError | null,\n    /** Equation combined with result expressed as unit */\n    resultEquation: EquationNode | EquationParserError | EquationResolveError | EquationRenderError,\n}\n```\n\nExample:\n\n```jsx\n\u003cEquationEvaluate\n    value='2 + a'\n    variables={{ a: { type: 'number', value: 5 }}}\n/\u003e\n// Renders a prettified 2 + a = 7\n```\n\n### `EquationPreparsed`\nRender a pre-parsed equation provided as `value`. No evaluation is done. This is mostly useful for building functionality on top of this library.\n\nExample:\n\n```jsx\n\u003cEquationPreparsed\n    value={{ type: 'plus', a: { type: 'number', value: '2' }, b: { type: 'variable', name: 'a' } }}\n/\u003e\n// Renders a prettified 2 + a\n```\n\n### `EquationEvaluatePreparsed`\nEvaluate a pre-parsed equation provided as `value` and render the formatted equation. This is mostly useful for building functionality on top of this library.\n\nExposes as ref:\n\n```ts\ntype RefValue = {\n    /** Equation can be evaluated */\n    valid: boolean,\n    /** Evaluated result of the equation */\n    result: ResultNode | ResultResolveError,\n    /** Evaluated result of the unit passed */\n    unitResult: ResultNode | ResultResolveError | null,\n    /** Equation combined with result expressed as unit */\n    resultEquation: EquationNode | EquationParserError | EquationResolveError,\n}\n```\n\nExample:\n\n```jsx\n\u003cEquationEvaluatePreparsed\n    value={{ type: 'plus', a: { type: 'number', value: '2' }, b: { type: 'variable', name: 'a' } }}\n    variables={{ a: { type: 'number', value: 5 }}}\n/\u003e\n// Renders a prettified 2 + a = 7\n```\n\n### `EquationContext\nRender multiple, interconnected equations, variables and functions. Variables\nand functions can be defined by simply assigning them (`x=2`, `f(x)=x^2`), and\nexpressions are evalutaed by ending them on an equals-sign (`2*3=`). Force\nconversion to a specific unit by ending on equals underscore-placeholder and the\nunit (`25in = _cm`).\n\n```tsx\n\u003cEquationContext render={(equation) =\u003e (\n   \u003c\u003e\n       {equation('a = 2')} Renders a = 2 and defines a\n       {equation('b = 5a =')} Renders b = 5a = 10 and defines b\n       {equation('c = 1/b = _ %')} Renders c = 1/b = 10% and defines c\n       {equation('f(x) = x^2')} Renders f(x) = x^2 and defines f(x)\n       {equation('2a + f(a) =')} Renders 2a + f(a) = 8\n   \u003c/\u003e\n)} /\u003e\n```\n\nIt is important to note, that since order matters, the equation-function from\nthis component should not be passed to other components. Instead, use\n`EquationOptions` and the `getOptions` helper.\n\n```tsx\n\u003cEquationContext render={(equation, getOptions) =\u003e (\n   \u003c\u003e\n       {equation('2x =')} Renders Unknown variable 'x'\n       \u003cEquationEvaluate value='2x' /\u003e Renders Unknown variable 'x'\n\n       {equation('x = 7')} Renders x = 7\n       {equation('2x =')} Renders 2x = 14\n       \u003cEquationEvaluate value='2x' /\u003e Renders Unknown variable 'x', not part of the context\n\n       \u003cEquationEvaluate value='2x' {...getOptions()} /\u003e Renders 2x = 14\n       \u003cEquationOptions {...getOptions()}\u003e\n           \u003cEquationEvaluate value='2x' /\u003e Renders 2x = 14\n       \u003c/EquationOptions\u003e\n   \u003c/\u003e\n)} /\u003e\n```\n\n## Error handling\nAn error handler should be added either to the `Equation`-components or to `EquationOptions`, otherwise the raw `errorType` of the error is shown. If english errors suffice, simply import `defaultErrorHandler`. If custom errors (for instance for localisation), see `./src/errorHandler.ts` for easy implementation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgram%2Freact-equation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkgram%2Freact-equation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgram%2Freact-equation/lists"}