Skylab React

Installation

npm install @avalara/skylab-sdk

Use

import { SAlert } from "@avalara/skylab-sdk/react";

Implementation notes

The react component registry exported at @avalara/skylab-sdk/react is initialized at runtime, and depends on the web components being registered. That is, it is important that the skylab scripts are included prior to the app bundle. See the section on scripts on the "installation" docs page.

Using props

All attributes and classes of Skylab SDK web components can be set, and custom events can be handled, via React props. See each component's docsite page for details about its API, and use the following guidelines to use the React version of the component.

Props are automatically mapped to the underlying web component's attributes. Use camel case when using Skylab's custom props (e.g. noDismiss={true} will create the nodismiss attribute and give it a value of "true"). However, do not use camel case for native HTML and ARIA attributes, such as aria-label or readonly.

Similarly, defining a handler for custom events on a React component will create an event listener on the underlying web component. For custom event handlers, use the "on" prefix, and include the leading "S-" in the event handler's name. In SAlert, for example, onS-dismiss={() => {}} will create a listener for the custom s-dismiss event on the s-alert web component and run the function you define in the React component when s-dismiss is fired.

If a Skylab web component attribute takes a stringified JSON value, pass the actual JSON object to the corresponding React prop.

React server-side rendering

The Skylab React library is not compatible with React server-side rendering or frameworks that use ReactDOM.hydrate(), such as Gatsby or Next.js. Our React components can be used with an Express rendering engine like Handlebars.

Migrating from Skylab SDK to Skylab React

Because each Skylab React component is imported individually from the node module, migration from web component to React component usage can be done incrementally, and you can feel free to use React components just for new development. If you choose to migrate existing Skylab SDK components, the two basic component categories will require different handling.

Native HTML elements

We will not be providing React-specific implementations of native HTML elements, such as <button> and <input>. Continue to use these native HTML elements as you normally would in React, following the guidelines in our documentation. Customizing the behavior (as opposed to the styling) of elements like these increases the likelihood of introducing bugs, and requires implementation of complex accessibility features, which adds bloat to our codebase without adding any value.

Custom element migration

Custom elements, which comprise all other Skylab SDK components (other than native HTML elements, such as <button>) have different requirements. As you replace existing attributes with props, you will pass in JavaScript objects or arrays instead of stringified JSON. You will also add event handler functions to components which previously had event listeners applied to them in the DOM. For example, this code:

<s-dialog aria-labelledby="dialog-title" aria-modal="true">
  <div slot="header" id="dialog-title">Header</div>
  <div slot="content">Content</div>
  <div slot="footer">Footer</div>
<s-dialog>

will become:

import { SDialog } from "@avalara/skylab-sdk/react";

// ...
<SDialog 
  open={isDialogOpen}
  onS-dismiss={(e) => handleDismissFunc(e)} 
  aria-labelledby="dialog-title" 
  aria-modal="true"
>
  <div slot="header" id="dialog-title">Header</div>
  <div slot="content">Content</div>
  <div slot="footer">Footer</div>
</SDialog>