svelte-helpers

---

Installation

npm i svelte-helpers --save

---

This library contains some helpers I've found useful for working with Svelte.

Spring helpers

svelte-helpers/spring-transitions has functions to help you use spring animations in an enter or exit transition.

springIn((from: number), (to: number), (springConfig: object));
springOut((from: number), (to: number), (springConfig: object));

Both of these functions return an object with a duration, and tickToValue property, for use in a Svelte transition. Duration is the duration of the given spring, while tickToValue is a lookup function that will return the spring's actual value for a given value of t in the transition's css function. For example:

import { springIn, springOut } from "svelte-helpers/spring-transitions";

const SPRING_IN = { stiffness: 0.1, damping: 0.1 };
const animateIn = node => {
  const { duration, tickToValue } = springIn(-80, 0, SPRING_IN);
  return {
    duration: duration,
    css: t => `transform: translateY(${tickToValue(t)}px)`
  };
};

const SPRING_OUT = { stiffness: 0.1, damping: 0.5, precision: 3 };
const animateOut = node => {
  const current = currentYTranslation(node);
  const { duration, tickToValue } = springOut(
    current ? current : 0,
    80,
    SPRING_OUT
  );

  return {
    duration: duration,
    css: t => `transform: translateY(${tickToValue(t)}px)`
  };
};

{#if open}
  <div in:animateIn out:animateOut class="box">
    Hello World!
  </div>
{/if}

Modal

A declarative modal component. Receives an open prop that, when true, renders the modal with an overlay behind it. The modal fires a close event when the user clicks outside the modal, or presses escape. The handler should ultimately cause your open prop to become false.

The modal and overlay will both animate in and out. These animations are not (yet) configurable.

<script>
  import Modal from "svelte-helpers/Modal";

  let modalOpen = false;
  const closeModal1 = () => (modalOpen = false);
</script>

<button on:click={openModal1}>Show Modal</button>

<Modal open={modalOpen} on:close={closeModal1}>
  <h1>Hi there</h1>
  <button on:click={() => (modalOpen = false)}>Close</button>
</Modal>

Live Demo

Here

Props

Prop	Type	Description
open	bool	Whether the modal is open
on:close	function	Called when the user clicks outside the modal, or presses escape. This should set state so the open prop becomes false
useContentWidth	bool	By default, the modal has a set, responsive width (that's overridable with css). Set this to true to have the modal's width size freely with your content
animateResizing	bool	By default changes to the modal's dimensions will animate. Pass false to turn this off.
deferStateChangeOnClose	bool	Used for conditionally rendering the modal itself. See below
modalKey	string	Used for conditionally rendering the modal itself. See below

Events

Name	Purpose
on:close	The modal has been closed. Use this method to set whatever state to reflect this closed state
on:closing	The modal's closing animation has started.
on:closed	The modal's closing animation has completed.
on:mount	The open modal's content has been mounted in the dom. Use this event to focus an input, etc

The Modal also has a closeModal method you can bind to, and call as needed.

{#if open3a}
  <Modal modalKey="modal3a" open={true} deferStateChangeOnClose={true} bind:closeModal={closeModal3a} on:close={() => (open3a = false)}>
    <button on:click={closeModal3a}>Close</button>
  </Modal>
{/if}

This can be used whether conditionally rendering (explained below), or not.

Conditional Rendering

If you need to conditionally render the modal, ie something like this

<script>
  import Modal from "svelte-helpers/Modal.svelte";
  let closeThisModal;
</script>

{#if open3}
  <Modal modalKey="modal3" open={true} deferStateChangeOnClose={true} on:close={() => (open3 = false)} useContentWidth={true} bind:closeModal={closeThisModal}>
    <ModalDemo2 />
  </Modal>
{/if}

Pass true to the deferStateChangeOnClose prop. Doing this will cause the close behavior of the modal to first run the standard exit animation, and then, once the modal is gone, fire the close event, to reset your state.

If you need to imperatively close a modal that's conditionally rendered, bind to the closeModal method, described above, or if inside a component rendered by the Modal, just grab the closeModal method from context, described below. If (and only if) conditionally rendering your modal, you need to use one of these two methods to close your modal imperatively. Do not just reset your state, since this will immediately unmount the modal's content, without the proper unmount animations.

Context

Within a modal there is a svelte-helpers-modal context value that's an object, with the following properties

Prop	Type	Description
closeModal	function	Closes the current modal. Can be used regardless of whether the modal is conditionally rendered.
isAnimatingResizing	writable<bool>	Writable store of a boolean value, that controls whether changes to the modal's dimensions are animated. This defaults to true, or whatever you pass to animateResizing, but can be changed any time. For example, you might flip it to false while running your own animations in the modal's content, and revert it to true when finished.

Style Overrides

The modal has a global css class of svelte-helpers-modal-content applied. Add your own overrides as needed.

AutoSuggest

<script>
  import AutoSuggest from "svelte-helpers/AutoSuggest";
</script>

<AutoSuggest filterField={'name'} displayField="name" placeholder="Search" {options}>
  <div slot="result" let:option>{option.name}</div>
  <span slot="no-results" style="color: blue">No Results, yo</span>
</AutoSuggest>

Live Demo

Here

Props

Prop	Type	Description
options	[object] or [string] or a function return either of those	The options to show. To disable an option, give it a disabled property set to true. If you pass a function returning your options, the options will not change when the results list is open. This can be a handy way to prevent your options list from jumping the moment you select one, if such a selection changes which options can be selected.
placeholder	string	The input's placeholder
inputStyles	string	The input's styles, if any
inputProps	object	Any props (attributes) you'd like to apply to the input
currentSearch	string	The currently searched for text. Bind to this if you'd like to control the input's value
onItemSelected	(item, inputElement) => void	Optional callback to call when an item is selected. By default the input will fill its value with the selected item's displayField if it's an object, or the item itself if it's a string. If this callback is provided, it will be called and nothing else will happen.
onBlur	() => void	Optional callback to call when the input loses focus
filterField	string	If options are objects, this specifies the prop to filter by
noFiltering	boolean	If true, no filtering will happen. Filter your options however you'd like, and pass them in
keyField	string	If options are objects, this specifies the key prop for Svelte's #each block. Array index will be used if not provided.
displayField	string	If options are objects, this specifies the prop to display when selected
filterByStartsWith	boolean = false	If true the options will filter based on a match from the start of the option. Otherwise options will filter based on a match anywhere in the option's text

Slots

result - the slot for each option the user is viewing
no-results - the slot to show when there are no results to display

CSS Overrides

The following CSS variables can be overridden to customize this component's appearance

Var	Purpose
--svelte-helpers-auto-complete-border-color	Border color for the input and options container
--svelte-helpers-auto-complete-border-width	Border width for the input and options container
--svelte-helpers-auto-complete-border-radius	Border radius for the input and options container
--svelte-helpers-auto-complete-option-padding	Padding of each result option
--svelte-helpers-auto-complete-results-max-height	Options container max height
--svelte-helpers-auto-complete-option-hover-background	Option background color when hovered
--svelte-helpers-auto-complete-option-cursor	Cursor for options
--svelte-helpers-auto-complete-options-background-color	Options container background color
--svelte-helpers-auto-complete-disabled-option-cursor	Cursor for disabled options