code-sample - Vaadin Add-on Directory
A wrapper element for highlight.js
# <code-sample>
[](https://travis-ci.org/kcmr/code-sample)
[](https://codecov.io/gh/kcmr/code-sample)
[](https://www.webcomponents.org/element/@kuscamara/code-sample)
[](https://badge.fury.io/js/%40kuscamara%2Fcode-sample)
> A wrapper element for [highlight.js](https://highlightjs.org/)
A themeable sample code snippet that uses [highlight.js](https://highlightjs.org/) for syntax highlighting.
Forget to worry about spaces, indentation, HTML entities, etc.
```html
```
## Installation
1. Install the component using Npm:
```bash
$ npm i -S @kuscamara/code-sample
```
2. Import Web Components loader (optional):
```html
```
3. Import the component:
```html
```
## Usage
The code to highlight must be provided inside a `` tag.
```html
```
### Used inside a custom element
When **used inside a custom element** you'll need to add the attribute `preserve-content` to the inner template to prevent Polymer to process the template's content.
```html
```
### Used inside a tagged template literal
When **used inside a tagged template literal** (Polymer or LitElement html function), you should escape any template string (`${expression}`) to prevent it from being evaluated getting an error.
```js
class SomeElement extends PolymerElement {
static get template() {
return html`
export class Example extends ExampleBase {
static get template() {
return html\`
`;
}
}
```
### Render the code inside the template
To render the code inside the template, use the boolean attribute `render`.
```html
```
### Copy to clipboard
To display a **copy to clipboard** button, use the boolean attribute `copy-clipboard-button`:
```html
```
### Language types
The `type` attribute specifies the language of the sample code (eg.: html, css, js) and is not needed most of the time because it's automatically set. You can use it when your code sample language is not properly detected.
```html
.some-class {
@apply --my-mixin;
}
```
**Exception**: for the case of **tagged template literals**, you may need to set the `type` attribute to **js**, **jsx** or **javascript** to prevent the code being formatted as HTML.
```html
class MyElement extends PolymerElement {
static get template() {
return html`
```
## Themes
The component includes 8 themes. One Dark is imported as the default theme.
To use another theme, import it and set as the `theme` property.
Example:
```html
```
### Available themes
- one-ligth.js as `oneLight`
- default.js as `defaultTheme`
- github.js as `github`
- one-dark.js as `oneDark`
- solarized-dark.js as `solarizedDark`
- solarized-light.js as `solarizedLight`
- kustom-light.js as `kustomLight`
- kustom-dark.js as `kustomDark`
### More themes
You can use your own theme by adding one of the [available themes](https://github.com/isagalaev/highlight.js/tree/master/src/styles) for hightlight.js in a shared style.
The shared style should be exported as a tagged template literal.
Example:
```js
import { html } from '@polymer/polymer/polymer-element.js';
export const myOwnTheme = html`
`;
```
### Themes in browsers using ShadyCSS
Due to **[ShadyCSS limitations](https://github.com/webcomponents/shadycss#dynamically-created-styles-are-not-supported)**, dynamic change of themes is **not supported in browsers that use ShadyCSS (Firefox)**. To set a different theme for these browsers, you should import your theme as a style module with `code-sample-theme` as its `id`.
**Example:**
In `your-shared-style-file.js`:
```js
const html = (string) => string;
const $documentContainer = document.createElement('div');
$documentContainer.setAttribute('style', 'display: none;');
$documentContainer.innerHTML = html`
`;
document.head.appendChild($documentContainer);
```
Import the shared style in the main document:
```html
```
The styles will be applied to `` in browsers using ShadyCSS.
### Languages included in the highlightjs pack included with the component:
- CSS
- HTTP
- JavaScript
- Bash
- CoffeScript
- JSON
- Markdown
- HTML, XML
highlightjs version: v9.12.0
### Styling
The following custom CSS properties are available for styling:
| Custom Property | Description | Default |
| :-------------- | :---------- | :------ |
| --code-sample-pre | empty mixin applied to `
Lorem ipsum dolor…
your code here...
your code here...
\${super.template}
\`; } }your code here...
Hello world!
`; } }` element | {} |
| --code-sample-font-family | font-family applied to `` and `` elements | Operator Mono, Inconsolata, Roboto Mono, monaco, consolas, monospace |
| --code-sample-font-size | font-size applied to `` and `` elements | 14px |
| --code-sample-line-height | line-height applied to `.hljs` | 1.3 |
| --code-sample-hljs | empty mixin applied to `.hljs` | {} |
| --code-sample-demo-padding | padding applied to the container of the rendered code | 0 0 20px |
| --code-sample-demo-not-empty | empty mixin applied to the demo container when is not empty | {} |
| --code-sample-demo | empty mixin applied to the container of the rendered code | {} |
| --code-sample-code-container | empty mixin applied to code container | {} |
| --code-sample-code-container-hover | empty mixin applied to code container on :hover | {} |
| --code-sample-code-container-hover-button | empty mixin applied to the copy to clipboard button when the code container on :hover | {} |
| --code-sample-copy-button-bg-color | background-color of the copy to clipboard button | #e0e0e0 |
| --code-sample-copy-clipboard-button | empty mixin applied to the copy to clipboard button | {} |
Included themes contain custom CSS properties to set the background and text color.
You may need to add these CSS properties to your own themes.
| Custom property | Description | Default |
|:-------------------------------|:----------------------------------------|:------------|
| --code-sample-background | code background color | Depends on the theme |
| --code-sample-color | code text color | Depends on the theme |