<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>.

Rendering with the preview already open

Add the open boolean attribute to render the preview already open.

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 + Property] `src`	The `iframe` src to use. This can be set to an external URL. This will override any HTML provided to the component.	`string`	`""`
[Attribute] `sandbox-settings` [Property] `sandboxSettings`	The sandbox settings to provide to the <iframe>	`string`	`"allow-downloads allow-forms allow-modals allow-pointer-lock allow-popups allow-presentation allow-scripts"`
[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>