` | A "Token" is an object that represents a piece of content for Prism. It has a `types` property, which is an array of types that indicate the purpose and styling of a piece of text, and a `content` property, which is the actual text. You'd typically iterate over `tokens`, rendering each line, and iterate over its items, rendering out each token, which is a piece of this line. ### prop getters > See > [Kent C. Dodds' blog post about prop getters](https://blog.kentcdodds.com/how-to-give-rendering-control-to-users-with-prop-getters-549eaef76acf) These functions are used to apply props to the elements that you render. This gives you maximum flexibility to render what, when, and wherever you like. You'd typically call these functions with some dictated input and add on all other props that it should pass through. It'll correctly override and modify the props that it returns to you, so passing props to it instead of adding them directly is advisable. | property | type | description | | --------------- | -------------- | ----------------------------------------------------------------------------------------------------- | | `getLineProps` | `function({})` | returns the props you should apply to any list of tokens, i.e. the element that contains your tokens. | | `getTokenProps` | `function({})` | returns the props you should apply to the elements displaying tokens that you render. | #### `getLineProps` You need to add a `line` property (type: `Token[]`) to the object you're passing to `getLineProps`. This getter will return you props to spread onto your line elements (typically `

s`). It will typically return a `className` (if you pass one it'll be appended), `children`, `style` (if you pass one it'll be merged). It also passes on all other props you pass to the input. The `className` will always contain `.token-line`. #### `getTokenProps` You need to add a `token` property (type: `Token`) to the object you're passing to `getTokenProps`. This getter will return you props to spread onto your token elements (typically `s`). It will typically return a `className` (if you pass one it'll be appended), `children`, `style` (if you pass one it'll be merged). It also passes on all other props you pass to the input. The `className` will always contain `.token`. This also provides full compatibility with your old Prism CSS-file themes. ## Utility Functions ### `useTokenize` > `(options: TokenizeOptions) => Token[][]` ```ts type TokenizeOptions = { prism: PrismLib code: string grammar?: PrismGrammar language: Language } ``` This is a React hook that tokenizes code using Prism. It returns an array of tokens that can be rendered using the built-in `` component or your own custom component. It uses `normalizeTokens` internally to convert the tokens into a shape that can be rendered. - `prism: PrismLib`: the Prism library to use for tokenization. This can be the vendored version of Prism that is included with `prism-react-renderer` or a custom version of Prism that you have configured. - `code: string`: a string containing the code to tokenize. - `grammar?: PrismGrammar`: a Prism grammar object to use for tokenization. If this is omitted, the tokens will just be normalized. A grammar can be obtained from `Prism.languages` or by importing a language from `prismjs/components/`. - `language: Language`: the language to use for tokenization. This should be a language that Prism supports. ### `normalizeTokens` > `(tokens: (PrismToken | string)[]) => Token[][]` Takes an array of Prism’s tokens and groups them by line, converting strings into tokens. Tokens can become recursive in some cases which means that their types are concatenated. Plain-string tokens however are always of type `plain`. - `PrismToken` is an internal alias for `Token` exported by `prismjs` and is defined [here](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/prismjs/index.d.ts#L347). - `Token` is an internal object that represents a slice of tokenized content for Prism with three properties: - `types: string[]`: an array of types that indicate the purpose and styling of a piece of text - `content: string`: the content of the token - `empty: boolean`: a flag indicating whether the token is empty or not. ## Theming The `defaultProps` you'd typically apply in a basic use-case, contain a default theme. This theme is [vsDark](./packages/prism-react-renderer/src/themes/vsDark.ts). While all `className`s are provided with ``, so that you could use your good old Prism CSS-file themes, you can also choose to use `prism-react-renderer`'s themes like so: ```jsx import { Highlight, themes } from 'prism-react-renderer'; ``` These themes are JSON-based and are heavily inspired by VSCode's theme format. Their syntax, expressed in Flow looks like the following: ```js { plain: StyleObj, styles: Array<{ types: string[], languages?: string[], style: StyleObj }> } ``` The `plain` property provides a base style-object. This style object is directly used in the `style` props that you'll receive from the prop getters, if a `theme` prop has been passed to ``. The `styles` property contains an array of definitions. Each definition contains a `style` property, that is also just a style object. These styles are limited by the `types` and `languages` properties. The `types` properties is an array of token types that Prism outputs. The `languages` property limits styles to highlighted languages. When converting a Prism CSS theme it's mostly just necessary to use classes as `types` and convert the declarations to object-style-syntax and put them on `style`. ## Upgrade If you are migrating from v1.x to v2.x, follow these steps ### Change module imports ```diff - import Highlight, { defaultProps } from "prism-react-renderer"; + import { Highlight } from "prism-react-renderer" const Content = ( - + ``` ### Change theme imports ```diff - const theme = require('prism-react-renderer/themes/github') + const theme = require('prism-react-renderer').themes.github ``` ### Check language support > By default prism-react-renderer only includes a base set of languages that Prism supports. Depending on your app's build system you may need to await the import or use require to ensure window.Prism exists before importing the custom languages. See: https://github.com/FormidableLabs/prism-react-renderer#custom-language-support Install prismjs (if not available yet): ``` # npm npm install --save prismjs # yarn yarn add prismjs # pnpm pnpm add prismjs ``` ### Add language component If the language is not already bundled in the above, you can add additional languages with the following code: ``` import { Highlight, Prism } from "prism-react-renderer"; (typeof global !== "undefined" ? global : window).Prism = Prism await import("prismjs/components/prism-applescript") /** or **/ require("prismjs/components/prism-applescript") ``` ## LICENSE MIT ## Maintenance Status **Active:** Nearform is actively working on this project, and we expect to continue work for the foreseeable future. Bug reports, feature requests and pull requests are welcome. [maintenance-image]: https://img.shields.io/badge/maintenance-active-green.svg

{item.name}