Annotated example component.yml

A YML metadata file is required in each single-directory component. Below is a sample component.component.yml file that identifies and explains each option.

Full example

# Everything in this file is optional. Still, the file needs to exist. 
# Adding metadata here will improve the DX when using components.

# Note: currently in Drupal 10.1, the schema will fail to validate if
# props section is not present. This may change in a future  release.

# This is so your IDE knows about the syntax for fixes and autocomplete.
$schema: https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/schemas/v1/metadata.schema.json

# The human readable name.
name: Tabs

# Status can be: "experimental", "stable", "deprecated", "obsolete".
status: experimental

# Use this key to organize components together.
group: Navigation

# Override components provided by other themes or modules. The format 
# is <module-or-theme-machineName>:<component-machineName>. Note that  
# only themes can override components. This will not work in modules.
replaces: 'sdc_module_test:my-component'

# Schema for the props. We support JSON Schema. Learn more about the
# syntax at https://json-schema.org
# The props section is currently required. See Components without
# Properties section below.
props:
  # Props are always an object with keys. Each key is a variable in your
  # component template.
  type: object

  # If your component has required properties, you list them here.
  required:
    - primary

  properties:
    # The key is the name of the variable in the template.
    primary:
      # You can add a human-readable name to your props.
      title: Primary
      # This variable is an array of strings: ['foo', 'bar', 'baz'].
      # This information is required for every prop.
      type: array
      items:
        type: string
    secondary:
      type: array
      title: Secondary
      description: You can describe your props
      items:
        type: string
    tertiary:
      type: string
      title: Tertiary
      # Limit the available options by using enums.
      enum:
        - success
        - warning
        - danger
      # Provide a default value. It isn't used in Twig template.
      default: success
    quaternary:
      type: ['string', 'null']
      title: Quaternary
      # Allow string or null.
      enum:
        - 'One'
        - 'Two'
        - 'Three'
        - null

# Slots always hold arbitrary markup. We know that beforehand, so no need
# for a schema for slots.
slots:
  # The key is the name of the slot. In your template you will use 
  # {% block body %}.
  body:
    # A human-readable name.
    title: Body
    # A description.
    description: This is the body

  # Only the key is required when declaring slots. This is how you 
  # declare a slot with minimal typing.
  minimal: {}

# This is how you take control of the keys in your library
# declaration. The overrides specified here will be merged (shallow merge)
# with the auto-generated library. The result of the merge will become the 
# library for the component.
libraryOverrides:
  # Once you add a key in the overrides, you take control of it. What you
  # type here is what will end up in the library component.
  dependencies:
    - core/drupal
    - core/once

  # Here we are taking control of the JS assets. So we need to specify
  # everything, even the parts that were auto-generated. This is useful
  # when adding additional files or tweaking the <script> 
  # tag's attributes.
  js:
    my-component.js: { attributes: { defer: true } }
    my-other-file.js: {}

Minimal example

# You can leave it empty.
# If you have a YAML linter (like core's) that won't allow empty YAML 
# files, use: null

Components without props, with a schema

# Everything from the Full example applies here. We are focusing on the
# props for this example.

# Even when we have no props, we need to add a schema of an empty object 
# for them.
props:
  type: object
  additionalProperties: false
  properties: {}

Add a remote schema on IDE

When editing or viewing an sdc *.component.yml file most modern IDEs will understand the top key $schema value and will use it to validate or suggest key - value pairs for the *.component.yml.

If your IDE does not understand by default the remote schema you can add it manually.

• PHPStorm: https://www.jetbrains.com/help/phpstorm/yaml.html#remote_json
• VSCode: https://code.visualstudio.com/Docs/languages/json#_json-schemas-and-sett...