Passing properties

Parcels allow you to pass in properties from the host application by setting HTML attributes. Functions are not accepted as property values.

<abyss-parcel
  import="my-parcel-one@2.0.0"
  user-name="John Doe"
  id="ABC123"
></abyss-parcel>

Reserved properties

import and auth are reserved property names. Any custom Parcel properties must not use these names.

Attribute naming

In HTML, attribute names are not case-sensitive. The browser will normalize them to lowercase. For example, if you write:

<abyss-parcel cartCount="5"></abyss-parcel>

The browser will normalize it to:

<abyss-parcel cartcount="5"></abyss-parcel>

To avoid confusion, use kebab-case for property names instead:

<abyss-parcel cart-count="5"></abyss-parcel>

This would be accessed in your Parcel component as:

export const ParcelApp = (args) => {
  const cartCount = args['cart-count'];
  // ...
};

When to use properties

Properties are best suited for initial configuration — data that the Parcel needs when it first mounts.

For runtime updates after the Parcel has mounted, see Updating Parcels.

Setting default properties

You can set default values for properties when developing your Parcel. You can set these default properties at a global level via the export default or on a story level with the args property.

// MyParcel.stories.jsx

import React from 'react';

import { MyParcel } from './MyParcel';

export default {
  title: 'MyParcel',
  parcel: 'my-parcel'
  component: MyParcel,
  args: {
    // All MyParcel stories will have these properties passed to them.
    'user-name': "John Doe",
    'sample-list': ['Create', 'Build', 'Use']
  },
};

// We create a “template” of how args map to rendering
const Template = (args) => {
  return <MyParcel {...args} />;
};

//Each story then reuses that template
export const Primary = Template.bind({});

// You can set per story properties by targeting the template
Primary.args = {
  'user-name': 'Jane Doe',
};

Viewing Properties in Storybook

When you define args in your Storybook configuration, Storybook's Controls panel shows the property names and values exactly as you wrote them.

Storybook configuration:

//...
export const Default: Story = {
  args: {
    count: 30,
  },
};

In Storybook's Controls panel, you'll see:

In production, your host application needs to send these same values to the Parcel via HTML attributes.

<abyss-parcel import="my-parcel-one@2.0.0" count="..."></abyss-parcel>