There are two ways to use vue-katex, using the KatexElement component or using the v-katex directive.
Global Options
Options applied globally through the plugin will be merged with any options applied locally to the v-katex directive or KatexElement. Locally applied options have a higher precedence and will override globally applied options, the exception to this is any KaTeX option of the type object or array. These will be merged with the resultant option containing all global and local keys or elements.
Using the katex directive
In your template (don't forget to escape all backslashes):
<divv-katex="'\\frac{a_i}{1+x}'"></div>
To render the math in display mode:
<divv-katex:display="'\\frac{a_i}{1+x}'"></div>
To add KaTeX options, use an object literal instead:
See KaTeX documentation for auto-render for more information.
Using the KatexElement component
<katex-elementexpression="'\\frac{a_i}{1+x}'"/>
Through props KatexElement supports all of the same options that KaTeX supports.
Props
expression
Type:StringRequired
A TeX expression to be displayed.
display-mode
Type:BooleanDefault:false
If true the math will be rendered in display mode, which will put the math in display style (so
\int and
\sum are large, for example), and will center the math on the page on its own line. If false the math will be rendered in inline mode.
throw-on-error
Type:BooleanDefault:false
If true, KaTeX will throw a
ParseError when it encounters an unsupported command or invalid LaTeX. If false, KaTeX will render unsupported commands as text, and render invalid LaTeX as its source code with hover text giving the error, in the color given by
errorColor.
error-color="#CC0000"
Type:StringDefault:#CC0000
A color string given in the format "#XXX" or "#XXXXXX". This option determines the color that unsupported commands and invalid LaTeX are rendered in when throwOnError is set to false.
macros
Type:ObjectDefault:null
A collection of custom macros. Each macro is a property with a name like
\name (written
"\\name" in JavaScript) which maps to a string that describes the expansion of the macro, or a function that accepts an instance of
MacroExpander as first argument and returns the expansion as a string.
MacroExpander is an internal API and subject to non-backwards compatible changes. See
src/macros.js for its usage. Single-character keys can also be included in which case the character will be redefined as the given macro (similar to TeX active characters). This object will be modified if the LaTeX code defines its own macros via
\gdef, which enables consecutive calls to KaTeX to share state.
color-is-text-color
Type:BooleanDefault:false
If true,
\color will work like LaTeX's
\textcolor, and take two arguments (e.g.,
\color{blue}{hello}), which restores the old behavior of KaTeX (pre-0.8.0). If false,
\color will work like LaTeX's
\color, and take one argument (e.g.,
\color{blue}hello). In both cases,
\textcolor works as in LaTeX (e.g.,
\textcolor{blue}{hello}).
max-size="Infinity"
Type:NumberDefault:Infinity
All user-specified sizes, e.g. in
\rule{500em}{500em}, will be capped to
maxSize ems. If set to
Infinity (the default), users can make elements and spaces arbitrarily large.
max-expand="1000"
Type:NumberDefault:1000
Limit the number of macro expansions to the specified number, to prevent e.g. infinite macro loops. If set to
Infinity, the macro expander will try to fully expand as in LaTeX.
Allowed protocols in
\href. Use
_relative to allow relative urls, and
* to allow all protocols.
strict
Type:[Boolean, String, Function]Default:"warn"
If
false or
"ignore", allow features that make writing LaTeX convenient but are not actually supported by (Xe)LaTeX (similar to MathJax). If
true or
"error" (LaTeX faithfulness mode), throw an error for any such transgressions. If
"warn" (the default), warn about such behavior via
console.warn. Provide a custom function
handler(errorCode, errorMsg, token) to customize behavior depending on the type of transgression (summarized by the string code
errorCode and detailed in
errorMsg); this function can also return
"ignore",
"error", or
"warn" to use a built-in behavior. A list of such features and their
errorCode:
"unknownSymbol": Use of unknown Unicode symbol, which will likely also lead to warnings about missing character metrics, and layouts may be incorrect (especially in terms of vertical heights).
"unicodeTextInMathMode": Use of Unicode text characters in math mode.
"mathVsTextUnits": Mismatch of math vs. text commands and units/mode.
"commentAtEnd": Use of % comment without a terminating newline. LaTeX would thereby comment out the end of math mode (e.g. $), causing an error. A second category of errorCodes never throw errors, but their strictness affects the behavior of KaTeX
"newLineInDisplayMode": Use of \ or \newline in display mode (outside an array/tabular environment). In strict mode, no line break results, as in LaTeX.
This adds support for the auto-render extension for katex (see here as requested by #10. As suggested by @lucpotage I've added an auto argument to v-katex such that applying v-katex:auto to an element will cause any Katex inside to be properly rendered. Options can be applied just as before with v-katex:auto="{options: {...} }".
Merging this PR will bump the version from 0.2.2 to 0.3.0. The auto-render feature does not cause any breaking changes in the API and is only additive.
My math equations are coming from a data source that could potentially contain html elements like <br>, <b>, <u> or <i>. Using the expression prop from vue-katex, I can't have it both ways. HTML rendered, or Math. Help me out here.
I've added the ability to apply KaTeX options globally via plugin options. Global options will be overwritten by options applied locally to v-katex or KatexElement.
Adding global options will add consistency to the KaTeX render within an entire app.
🔧 Additional Changes
🚀 Version change
With the addition of the global options feature I have incremented the minor version from 0.3.0 to 0.4.0 to denote a non breaking API change.
✍️ Tests
Many of the tests for v-katex were rewritten to use mocks instead of snapshots. This makes them easier to maintain and applies a better separation of concerns to them. By mocking katex, it is easier to verify the arguments given to katex are valid.
Hi,
is there any plan to support the auto-render extension?
I'm looking for a way to render all the math in some text without having to specify directives or KatexElement components for each expression since the text is retrieved dynamically and these wouldn't work...
Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR:
@dependabot rebase will rebase this PR
@dependabot recreate will recreate this PR, overwriting any edits that have been made to it
@dependabot merge will merge this PR after your CI passes on it
@dependabot squash and merge will squash and merge this PR after your CI passes on it
@dependabot cancel merge will cancel a previously requested merge and block automerging
@dependabot reopen will reopen this PR if it is closed
@dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
@dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
@dependabot use these labels will set the current labels as the default for future PRs for this repo and language
@dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
@dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
@dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language
You can disable automated security fix PRs for this repo from the Security Alerts page.
Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR:
@dependabot rebase will rebase this PR
@dependabot recreate will recreate this PR, overwriting any edits that have been made to it
@dependabot merge will merge this PR after your CI passes on it
@dependabot squash and merge will squash and merge this PR after your CI passes on it
@dependabot cancel merge will cancel a previously requested merge and block automerging
@dependabot reopen will reopen this PR if it is closed
@dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
@dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
@dependabot use these labels will set the current labels as the default for future PRs for this repo and language
@dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
@dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
@dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language
You can disable automated security fix PRs for this repo from the Security Alerts page.
Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR:
@dependabot rebase will rebase this PR
@dependabot recreate will recreate this PR, overwriting any edits that have been made to it
@dependabot merge will merge this PR after your CI passes on it
@dependabot squash and merge will squash and merge this PR after your CI passes on it
@dependabot cancel merge will cancel a previously requested merge and block automerging
@dependabot reopen will reopen this PR if it is closed
@dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
@dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
@dependabot use these labels will set the current labels as the default for future PRs for this repo and language
@dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
@dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
@dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language
You can disable automated security fix PRs for this repo from the Security Alerts page.
I have made changes so that I can use this with Vue 3. I hope you don't mind but I published a namespaced version (@hsorby/vue3-katex) so that I can use it now. Happy to make further changes to this PR to bring it more inline with existing codebase, otherwise it will serve as a place for people to (maybe) find out that there is a Vue 3 option available.
when building a vite app that uses vue-katex, the build breaks due to const merge = require('deepmerge')
i've been able to fix this manually by copying the katex-directive.js code in my plugin.js file, and changing the line above to import merge from 'deepmerge'
This version was pushed to npm by hargasinski, a new releaser for async since your current version.
Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR:
@dependabot rebase will rebase this PR
@dependabot recreate will recreate this PR, overwriting any edits that have been made to it
@dependabot merge will merge this PR after your CI passes on it
@dependabot squash and merge will squash and merge this PR after your CI passes on it
@dependabot cancel merge will cancel a previously requested merge and block automerging
@dependabot reopen will reopen this PR if it is closed
@dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
@dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
@dependabot use these labels will set the current labels as the default for future PRs for this repo and language
@dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
@dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
@dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language
You can disable automated security fix PRs for this repo from the Security Alerts page.