<light-preview>

LightPreview is a very lightweight code previewer designed to load your code sample inside of an iFrame for encapsulated viewing. <light-preview> uses PrismJS as it’s

Examples

Nesting a light-preview inside of a light-preview

Loading inside a shadow DOM

By default, previews are loaded inside an <iframe> for true “encapsulation”. This may not always be desirable. For not as strict encapsulation you can use preview-mode="shadow-dom"

Adding Additional buttons

Escaping nested script tags

Highlight Lines

If you check the source code in the above example, you’ll notice a </script>.

Additional Notes

For more on why script tags are used, check out Why script tags for further reading.

API Reference

Imports

Script

HTML

<!-- Auto registers as <light-preview> -->
<script type="module" src="https://cdn.jsdelivr.net/npm/light-pen/exports/components/light-preview/light-preview-register.js"></script>

CDN

HTML

<script type="module">
  // Auto registers as <light-preview>
  import "https://cdn.jsdelivr.net/npm/light-pen/exports/components/light-preview/light-preview-register.js"

  // Manual Register
  import LightPreview from "https://cdn.jsdelivr.net/npm/light-pen/exports/components/light-preview/light-preview.js"
  LightPreview.define()
  // => Registers as <light-preview>
</script>

Bundler

JavaScript

// Auto registers as <light-preview>
import "light-pen/exports/components/light-preview/light-preview-register.js"

// Manual Register
import LightPreview "light-pen/exports/components/light-preview/light-preview.js"
LightPreview.define()
// => Registers as <light-preview>

Slots

Name	Description
`resize-icon`	The icon to display in the resizer button. Override this to provide your own icon.
`summary`	What to display in source code expander
`source-code-toggle-icon`	Slot in your own icon to override the default caret.
`above-actions`	Additional actions placed above the source code toggle
`below-actions`	Additional actions placed above the source code toggle
`actions`	Slot in buttons / links to allow for additional actions in the bottom bar. These are placed inline.
`preview-html`	If you want to run code that is slightly different from the source code you want to display, slot it into “preview-html”
`code`	Used to display both source code and to power your preview in the iframe. If you slot in “preview-html”, then it will only be used to show / highlight your source code.
`before-expanded-code`	A slot to add actions such as buttons. This will sit above the source-code-toggle, and when code is expanded, will be above the expanded code.
`after-expanded-code`	A slot to add actions such as buttons. This will sit above the source-code-toggle, and when code is expanded, will be below the expanded code.
`after-actions`	A slot add actions below the source-code-toggle button.

Attributes

Name	Description	Type	Default
[Attribute] `sandbox-settings` [Property] `sandboxSettings`	The sandbox settings to provide to the <iframe>	`string`	`""`
[Attribute + Property] `summary`	The text to provide in the toggle button	`string`	`"Show source code"`
[Attribute] `preview-mode` [Property] `previewMode`	Set to true to not use an <iframe> for previewing	`"iframe" \| "shadow-dom"`	`"iframe"`
[Attribute + Property] `resizing`	When the resizer is being dragged, this will be true.	`boolean`	`false`
[Attribute] `preview-html` [Property] `previewHtml`	If `disableHighlight` is true, then you must pass in an element into `previewHtml` to be able to get the code to run in the previewer.	`string`	`""`
[Attribute + Property] `open`	Whether or not the source code is being shown	`boolean`	`false`
[Attribute] `resize-position` [Property] `resizePosition`	The current position of the resizer. 100 means all the way to right. 0 means all the way to left.	`number`	`100`
[Attribute] `script-scope` [Property] `scriptScope`	When using `preview-mode="shadow-dom"`, There’s a funky issue with previews where if you want the location of the shadowRoot you are, you can’t get it. As a result, `<light-preview>` supports the idea of a “scriptScope” where `document` is bound to the current shadowRoot instead of the actual top level `document` For more info, check out this GitHub issue:	`"document" \| "shadow-dom"`	`"document"`
[Attribute + Property] `language`	The language to highlight for.	`string`	`"html"`
[Attribute] `preserve-whitespace` [Property] `preserveWhitespace`	Preserve leading and trailing whitespace.	`boolean`	`false`
[Attribute] `disable-highlight` [Property] `disableHighlight`	If disabled, its on you to provide `<pre><code></code></pre>`	`boolean`	`false`
[Attribute] `highlight-lines` [Property] `highlightLines`	A string of possible lines to highlight. Example: “{1-9, 16, 18}”	`string`	`""`
[Attribute] `inserted-lines` [Property] `insertedLines`	A string of lines that are inserted for diffs. Example: “{1-9, 16, 18}”	`string`	`""`
[Attribute] `deleted-lines` [Property] `deletedLines`	A string of lines that are deleted for diffs. Example: “{1-9, 16, 18}”	`string`	`""`
[Attribute] `disable-line-numbers` [Property] `disableLineNumbers`	whether or not to disable line numbers	`boolean`	`false`
[Attribute] `line-number-start` [Property] `lineNumberStart`	Where to start counting indexes in the gutter. Note, this is purely for display purposes.	`number`	`1`
[Attribute + Property] `code`	We will take the code, wrap it in `<pre><code></code></pre>` and run it through Prism.js. If the element has `disableHighlight`, we will not touch their code. Instead they must pass in escapedHTML.	`string`	`""`
[Attribute + Property] `wrap`	If `wrap="soft"`, lines will wrap when they reach the edge of their container. If `wrap="none"`, lines will not wrap instead all the user to scroll horizontally to see more code.	`"soft" \| "hard"`	`"soft"`
[Attribute] `unescape-behavior` [Property] `unescapeBehavior`	Whether or not to transform `</script>` into `<script>` If true, will run transform. If false, will leave the code as is.	`"all" \| "last" \| "none"`	`"last"`

Functions

Name	Description	Parameters
`highlight()`	-	`code`
`addShadowRootToPreview()`	-	`root: HTMLElement \| Element \| ShadowRoot`

Parts

Name	Description
`base`	The base wrapping element
`preview`	The wrapper around the iframe / div preview showing your code being run in the browser.
`start-panel`	The iframe or preview-div
`preview-div`	used for inline previews
`iframe`	used for iframe based previews (default)
`panel-resizer`	The button that resizes the panel
`end-panel`	The white space when dragging the resizer
`source-details`	The details element that shows the source code
`code-wrapper`	The div that wraps the <pre> + `elements containing your highlighted code`
`pre`	The <pre> element wrapping the source code
`code`	The `element wrapping the source code`
`source-code-toggle`	The button to show the source code
`actions`	The buttons at the bottom of the code previewer
`before-expanded-code`	A wrapper around the “before-expanded-code” slot
`after-expanded-code`	A wrapper around the “after-expanded-code” slot
`after-actions`	A wrapper around the “after-actions” slot
`source-code-toggle-icon`	The caret icon in the source code toggle

<light-pen>