svelte-hyperscript

svelte-hyperscript

use hyperscript to create svelte components

What?

This package exposes an hyperscript compatible function: h(tag, properties, ...children) which returns a svelte component.

Why?

This is the core for svelte-jsx and [svelte-htm]. These packages allow to simplify svelte testing code especially slot handling.

Installation

npm install svelte-hyperscript

And then import it:

// using es modules
import h from 'svelte-hyperscript'

// common.js
const h = require('svelte-hyperscript')

Alternatively use UNPKG or jsDelivr packages:

With script tags and globals:

<!-- UNPKG -->
<script src="https://unpkg.com/svelte-hyperscript"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/svelte-hyperscript"></script>

<script>
  <!-- And then grab it off the global like so: -->
  const h = svelteHyperscript
</script>

Hotlinking from unpkg: (no build tool needed!)

import h from 'https://unpkg.com/svelte-hyperscript?module'

Usage

import h from 'svelte-hyperscript'

import Button from '../src/Button.svelte'

let clicked = 0
const LabeledButton = h(Button, { 'on:click': () => (clicked += 1) }, h('span', null, 'Click Me!'))

const button = new LabeledButton({
  target: document.body,
})

The above example written in jsx using svelte-jsx:

import Button from '../src/Button.svelte'

let clicked = 0
const LabeledButton = (
  <Button onClick={() => (clicked += 1)}>
    <span>Click Me!</span>
  </Button>
)

const button = new LabeledButton({
  target: document.body,
})

or using [svelte-htm]:

import html from 'svelte-htm'
import Button from '../src/Button.svelte'

let clicked = 0
const LabeledButton = html`<${Button} on:click=${() => (clicked += 1)}><span>Click Me!</span><//>`

const button = new LabeledButton({
  target: document.body,
})

API

We aim to support all svelte features. In some cases this is not possible due to the static nature of hyperscript. For those cases we provided feasible workarounds:

Using stores to allow reactivity

To allow reactivity the following properties accept a writable store:

• bind:property
• bind:group
• bind:this
• <slot let:name={value}>

<slot let:name={value}> additionally accepts a function which is called with the current value.

This allows to for example to access the value if an input:

import { test } from '@jest/globals'
import { render } from '@testing-library/svelte'
import userEvent from '@testing-library/user-event'

import { writable, get } from 'svelte/store'

import h from 'svelte-hyperscript'

test('write into an input', () => {
  const text = writable()
  const { getByRole } = render(h('input', { 'bind:value': text }))

  const input = getByRole('textbox')

  await userEvent.type(input, 'some text')

  expect(get(text)).toBe('some text')
})

The tests are a good source of how to use this feature.

Action factories

The action feature of svelte is supported but lacks the possibility to pass parameters to the action. This can still be achieved using a factory function as action:

import h from 'svelte-hyperscript'

import action from 'some-action-module'

h('div', { 'use:action': (node) => action(node, parameters) })

Related Projects

• svelte-jsx - write svelte components using jsx
• [svelte-htm] - Hyperscript Tagged Markup for svelte
• svelte-fragment-component - a utility component

Feature Set

• plain html children
• readable store children
• on:eventname
• on:eventname modifiers
• bind:property but using writable store
  • bind:property on components
  • bind:property on html elements
  • bind:group
  • bind:this
• use:action
• class:name
• transition:fn
• in:fn/out:fn
• <slot>
  • <slot name="name">
  • <slot let:name={setter}> but using setter or writable store
  • <slot let:name={property}>{property}</slot> when using a writable store
• context propagation
• svelte:self
• svelte:component
• svelte:window
• svelte:body
• svelte:head

Support

This project is free and open-source, so if you think this project can help you or anyone else, you may star it on GitHub. Feel free to open an issue if you have any idea, question, or you've found a bug.

Contribute

Thanks for being willing to contribute!

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

We are following the Conventional Commits convention.

Develop

• npm test: Run test suite
• npm run build: Generate bundles
• npm run lint: Lints code

NPM Statistics

License

svelte-hyperscript is open source software licensed as MIT.

Changelog

1.2.1 (2020-06-29)

Bug Fixes

• typescript declaration (0f21f0e)