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>

Note: import and auth are reserved property names.

Attribute naming

In HTML, attribute names are not case-sensitive. The browser will normalize them to lowercase. This means camelCase names like cartCount will be stored as cartcount in the DOM.

Example:

If you write:

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

The browser will normalize it to:

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

Best practice: Use kebab-case for property names to avoid confusion:

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

Then in your Parcel component, access it 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>