API Formats

Overview

Topic	Guidelines
Boolean	Try to use the predefined boolean words
String	Use the predefined conventions for levels and hierarchy
Value of None	Don't use null and undefined

Example Prop in a Schema.yml

string-prop-name:
  type: string
  title: Prop Name
  description: Prop description sentence.
  default: medium
  enum:
    - large
    - medium
    - small
boolean-prop-name:
  type: boolean
  title: Prop Name
  description: Prop description sentence.
  default: false

Boolean

All boolean props should default to FALSE

• If you want a behavior that defaults to TRUE, then use a negative boolean prop. For example, if images should lazy load by default, use a "nolazy" prop so that users must explicitly opt out.
• This allows web components to always get the default value by simply omitting the prop

Changing the default of a boolean is not trivial

Changing the default is always a breaking change because usages that require the previous default would not have been passing a value at all.

For example, if images lazy loaded by default and you wanted to not lazy load by default, you'd have to:

• Add a new boolean property that did the opposite of the old one. In this case, you'd add "lazy" to replace the existing "nolazy"
• Remove the old property. This would have to be done in a major release, because it's impossible to write an adaptor for it.

Naming

The following are examples of positive and negative boolean naming. When possible, use a value from this table when adding a boolean prop.

Note that all the words in the table are adjectives or verbs. If your prop name makes more sense as a noun (e.g. "subtitles"), you should prefix it with a modifier like is or has (e.g. "has-subtitles").

Positive Boolean	Negative Boolean	Neutral Boolean
		indeterminate
loop	unloop
autoplay	noautoplay
checked	unchecked
enabled	disabled
active	inactive
selected	unselected
toggled	untoggled
interactive	nointeractive
styled	unstyled
clicked	unclicked
rounded	unrounded
visible	hidden, visuallyhidden

String

Don't Use String For Something Boolean

If it's boolean, use boolean. If it's more than just true or false, use string.

Don't do this:

{% include "@bolt/component-name.twig" with {
  rounded: "rounded"
} %}

Related API conventions

View on Gitlab

Value of None:

theme:
  type: string
  title: 'Theme'
  description: 'Color theme options.'
  default: xlight
  enum:
    - xlight
    - light
    - dark
    - xdark
    - none

In the above example, to truly remove theme, one has to explicitly set it to none. Since that's not boolean, true, false, and null would not work, only values from the schema would work. But these values won't be invalid, they will just return the schema default.

Never use null or undefined

The following is invalid, don't do it.

{% include "@bolt/component-name.twig" with {
  prop1: null,
  prop2: ""
} %}