Concorde documentation (crawl) · interactive version

Concorde guide — Creating components. > New app components: start with My first component and Data flow. The Subscriber mixin below is legacy. Doc ID: docs/_getting-started/create-a-component. Keywords: Concorde, supersoniks, docs/_getting-started/create-a-component, create-a-component, Creating components, guide, Subscriber, core, /components/destination/, /components/atoms, example.ts, ${this.text}. URL: https://concorde.supersoniks.org/crawl/docs/_getting-started/create-a-component.html.

Creating components

New app components: start with My first component and Data flow. The Subscriber mixin below is legacy.

Where to put it?

In this document, we consider the src directory of the project as the root.
We describe how we organize our components as an example, however it depends on your project.

In concorde each component is currently organized in the following directory structure (at least we try):

Starting from a Simple Model

You can copy example.ts from the source to the desired destination to start with. This file contains a web component in the form of a class that extends the Subscriber mixin, with a reactive property and a render function.

import { html, LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";
import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";

@customElement("sonic-example")
export class SonicComponent extends Subscriber(LitElement) {
  @property() text = "Example";
  render() {
    return html`${this.text}`;
  }
}

You can remove the dependency on Subscriber if automatic population of the component with external data is not required. For example, for a UI component:

import { html, LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";

@customElement("sonic-example")
export class SonicComponent extends LitElement {
  @property() text = "Example";
  render() {
    return html`${this.text}`;
  }
}

Regarding Subscriber, see:

Naming the Component

The class name is not necessarily important. However, it is important to give it a component name prefixed with "sonic" (or a prefix of your own) using the dedicated metadata already present in the copied document. For example, a button component would be named as follows:

@customElement("sonic-button")

For less generic components with a specific destination, we advise to include the destination in the name. For example, for a "title" component in the "event" destination, the name would be simply:

@customElement("sonic-event-title")

Modifying It

Creating Reactive Properties and Modifying the Render Function

To do this, study the functioning of https://lit.dev and also refer to Subscriber.

HTML Structure of a Component

The HTML structure of a component should remain as simple as possible.

Ideally, there should be only one additional level of elements in addition to slots.

This leads to the creation of more components and thus raises questions about the hierarchical organization of files. However, this tends to atomize their roles.

Referencing It

To compile the component, it needs to be referenced somewhere through an import statement. In particular, it is important to reference it in any component that uses it.

In the case where it can be directly used in a page, it should also be globally referenced, especially considering the creation of specific bundles in the future.

Here's where we add imports based on the component's location inside concorde as an example

Using It

As a reminder, the component is simply integrated into the context by adding a tag with the component's name, for example:

<sonic-event-title></sonic-event-title>