Lightweight, robust, elegant virtual syntax highlighting usingPrism.
- What is this?
- When should I use this?
- Playground
- Install
- Use
- API
- Examples
- Types
- Data
- CSS
- Compatibility
- Security
- Related
- Projects
- Contribute
This package wrapsPrismto output objects (ASTs) instead of a string of HTML.
Prism, through refractor, supports 270+ programming languages. Supporting all of them requires a lot of code. That’s why there are three entry points for refractor:
lib/core.js— 0 languageslib/common.js(default) — 36 languageslib/all.js— 297 languages
Bundled, minified, and gzipped, those are roughly 12.7 kB, 40 kB, and 211 kB.
This package is useful when you want to perform syntax highlighting in a place where serialized HTML wouldn’t work or wouldn’t work well. For example, you can use refractor when you want to show code in a CLI by rendering to ANSI sequences, when you’re using virtual DOM frameworks (such as React or Preact) so that diffing can be performant, or when you’re working with ASTs (rehype).
A different package,lowlight,does the same as refractor but
useshighlight.jsinstead.
If you’re looking for areally good(but rather heavy) highlighter, try
starry-night.
You can play with refractor on the interactive demo (Replit).
This package isESM only. In Node.js (version 14.14+, 16.0+), install withnpm:
npm install refractorIn Deno withesm.sh:
import{refractor}from'https://esm.sh/refractor@4'In browsers withesm.sh:
<scripttype= "module">
import{refractor}from'https://esm.sh/refractor@4?bundle'
</script>import{refractor}from'refractor'
consttree=refractor.highlight(' "use strict";','js')
console.log(tree)Yields:
{
type:'root',
children:[
{
type:'element',
tagName:'span',
properties:{className:['token','string']},
children:[{type:'text',value:' "use strict" '}]
},
{
type:'element',
tagName:'span',
properties:{className:['token','punctuation']},
children:[{type:'text',value:';'}]
}
]
}This package exports the identifierrefractor.
There is no default export.
Highlightvalue(code) aslanguage(programming language).
value(string) — code to highlightlanguage(stringorGrammar) — programming language name, alias, or grammar.
Node representing highlighted code (Root).
import{refractor}from'refractor/lib/core.js'
importcssfrom'refractor/lang/css.js'
refractor.register(css)
console.log(refractor.highlight('em { color: red }','css'))Yields:
{
type:'root',
children:[
{type:'element',tagName:'span',properties:[Object],children:[Array]},
{type:'text',value:' '},
//…
{type:'text',value:' red '},
{type:'element',tagName:'span',properties:[Object],children:[Array]}
]
}Register a syntax.
syntax(Function) — language function custom made for refractor, as in, the files inrefractor/lang/*.js
import{refractor}from'refractor/lib/core.js'
importmarkdownfrom'refractor/lang/markdown.js'
refractor.register(markdown)
console.log(refractor.highlight('*Emphasis*','markdown'))Yields:
{
type:'root',
children:[
{type:'element',tagName:'span',properties:[Object],children:[Array]}
]
}Register aliases for already registered languages.
alias(name, alias|list)alias(aliases)
language(string) — programming languagenamealias(string) — new aliases for the programming languagelist(Array<string>) — list of aliasesaliases(Record<language, alias|list>) — map oflanguages toaliases orlists
import{refractor}from'refractor/lib/core.js'
importmarkdownfrom'refractor/lang/markdown.js'
refractor.register(markdown)
// refractor.highlight('*Emphasis*', 'mdown')
// ^ would throw: Error: Unknown language: `mdown` is not registered
refractor.alias({markdown:['mdown','mkdn','mdwn','ron']})
refractor.highlight('*Emphasis*','mdown')
// ^ Works!Check whether analiasorlanguageis registered.
aliasOrlanguage(string) — programming language name or alias
import{refractor}from'refractor/lib/core.js'
importmarkdownfrom'refractor/lang/markdown.js'
console.log(refractor.registered('markdown'))//=> false
refractor.register(markdown)
console.log(refractor.registered('markdown'))//=> trueList all registered languages (names and aliases).
Array<string>.
import{refractor}from'refractor/lib/core.js'
importmarkdownfrom'refractor/lang/markdown.js'
console.log(refractor.listLanguages())//=> []
refractor.register(markdown)
console.log(refractor.listLanguages())Yields:
[
'markup',// Note that `markup` (a lot of xml based languages) is a dep of markdown.
'html',
//…
'markdown',
'md'
]hast trees as returned by refractor can be serialized with
hast-util-to-html:
import{refractor}from'refractor'
import{toHtml}from'hast-util-to-html'
consttree=refractor.highlight(' "use strict";','js')
console.log(toHtml(tree))Yields:
<spanclass= "token string">"use strict"</span><spanclass= "token punctuation">;</span>hast trees as returned by refractor can be turned into React (or Preact) with
hast-to-hyperscript:
import{refractor}from'refractor'
import{toH}from'hast-to-hyperscript'
importReactfrom'react'
consttree=refractor.highlight(' "use strict";','js')
constreact=toH(React.createElement,tree)
console.log(react)Yields:
{
'$$typeof':Symbol(react.element),
type:'div',
key:'h-1',
ref:null,
props:{children:[[Object],[Object]]},
_owner:null,
_store:{}
}This package is fully typed withTypeScript.
It exports the additional typesRoot,Grammar,andSyntax.
If you’re usingrefractor/lib/core.js,no syntaxes are included.
Checked syntaxes are included if you importrefractor(or explicitly
refractor/lib/common.js).
Unchecked syntaxes are available throughrefractor/lib/all.js.
You can importcoreorcommonand manually add more languages as you please.
Prism operates as a singleton: once you register a language in one place, it’ll be available everywhere.
Only these custom built syntaxes will work withrefractorbecause Prism’s own
syntaxes are made to work with global variables and are not importable.
arduino— alias:inobash— alias:sh,shellbasiccclikecppcsharp— alias:cs,dotnetcssdiffgoinijavajavascript— alias:jsjson— alias:webmanifestkotlin— alias:kt,ktslessluamakefilemarkdown— alias:mdmarkup— alias:atom,html,mathml,rss,ssml,svg,xmlmarkup-templatingobjectivec— alias:objcperlphppython— alias:pyrregexruby— alias:rbrustsassscsssqlswifttypescript— alias:tsvbnetyaml— alias:ymlabapabnfactionscriptadaagdaalantlr4— alias:g4apacheconfapexaplapplescriptaqlarffarmasm— alias:arm-asmarturo— alias:artasciidoc— alias:adocasm6502asmatmelaspnetautohotkeyautoitavisynth— alias:avsavro-idl— alias:avdlawk— alias:gawkbatchbbcode— alias:shortcodebbjbicepbirbbisonbnf— alias:rbnfbqnbrainfuckbrightscriptbrobsl— alias:oscriptcfscript— alias:cfcchaiscriptcilcilkc— alias:cilk-ccilkcpp— alias:cilk,cilk-cppclojurecmakecobolcoffeescript— alias:coffeeconcurnas— alias:conccooklangcoqcrystalcshtml— alias:razorcspcss-extrascsvcuecypherddartdataweavedaxdhalldjango— alias:jinja2dns-zone-file— alias:dns-zonedocker— alias:dockerfiledot— alias:gvebnfeditorconfigeiffelejs— alias:etaelixirelmerberlangetluaexcel-formula— alias:xls,xlsxfactorfalsefirestore-security-rulesflowfortranfsharpftlgapgcodegdscriptgedcomgettext— alias:pogherkingitglslgml— alias:gamemakerlanguagegn— alias:gnigo-module— alias:go-modgradlegraphqlgroovyhamlhandlebars— alias:hbs,mustachehaskell— alias:hshaxehclhlslhoonhpkphstshttpichigojamiconicu-message-formatidris— alias:idriecstignore— alias:gitignore,hgignore,npmignoreinform7iojjavadocjavadoclikejavastacktracejexljoliejqjs-extrasjs-templatesjsdocjson5jsonpjsstacktracejsxjuliakeepalivedkeymankumir— alias:kumkustolatex— alias:context,texlattelilypond— alias:lylinker-script— alias:ldliquidlisp— alias:elisp,emacs,emacs-lisplivescriptllvmloglolcodemagmamatamatlabmaxscriptmelmermaidmetafontmizarmongodbmonkeymoonscript— alias:moonn1qln4js— alias:n4jsdnand2tetris-hdlnaniscript— alias:naninasmneonnevodnginxnimnixnsisocamlodinopenclopenqasm— alias:qasmozparigpparserpascal— alias:objectpascalpascaligopcaxis— alias:pxpeoplecode— alias:pcodephp-extrasphpdocplant-uml— alias:plantumlplsqlpowerquery— alias:mscript,pqpowershellprocessingprologpromqlpropertiesprotobufpslpugpuppetpurepurebasic— alias:pbfasmpurescript— alias:pursqqmlqoreqsharp— alias:qsracket— alias:rktreasonregorenpy— alias:rpyrescript— alias:resrestriproboconfrobotframework— alias:robotsasscalaschemeshell-session— alias:sh-session,shellsessionsmalismalltalksmartysml— alias:smlnjsolidity— alias:solsolution-file— alias:slnsoysparql— alias:rqsplunk-splsqfsquirrelstanstatastylussupercollider— alias:sclangsystemdt4-cs— alias:t4t4-templatingt4-vbtaptcltextiletomltremor— alias:trickle,troytsxtt2turtle— alias:trigtwigtyposcript— alias:tsconfigunrealscript— alias:uc,uscriptuorazoruri— alias:urlvvalavelocityverilogvhdlvimvisual-basic— alias:vb,vbawarpscriptwasmweb-idl— alias:webidlwgslwikiwolfram— alias:mathematica,nb,wlwrenxeora— alias:xeoracubexml-docxojoxqueryyangzig
refractordoes not inject CSS for the syntax highlighted code (because well,
refractor doesn’t have to be turned into HTML and might not run in a browser!).
If you are in a browser, you can use any Prism theme.
For example, to get Prism Dark from cdnjs:
<linkrel= "stylesheet"href= "https://cdnjs.cloudflare.com/ajax/libs/prism/1.27.0/themes/prism-dark.min.css">This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. It also works in Deno and modern browsers.
Only the custom built syntaxes inrefractor/lang/*.jswill work with
refractoras Prism’s own syntaxes are made to work with global variables and
are not importable.
refractor also does not support Prism plugins, due to the same limitations, and that they almost exclusively deal with the DOM.
This package is safe.
lowlight— the same as refractor but withhighlight.jsstarry-night— similar but like GitHub and really good
react-syntax-highlighter—Reactcomponent for syntax highlighting@mapbox/rehype-prism—rehypeplugin to highlight code blocksreact-refractor— syntax highlighter forReact
Yes please! SeeHow to Contribute to Open Source.
