CSS Customization

Styling Cord components

Cord components are web components and so they can be styled as any other HTML element – using CSS. For example, to add a shadow to every cord-thread component, you would use this CSS:

cord-thread {
  box-shadow: 10px 10px grey;
}

However, sometimes simple CSS is not enough. For example, if you want to change the color of the send button there is no CSS selector that would allow you to target the send button inside a cord-thread. This is because the internal HTML structure of Cord components is hidden from you behind a shadow DOM. The shadow DOM encapsulates the internal HTML of Cord components, which hides it from your CSS selectors. This is done to avoid your page's CSS unintentionally changing the styles of Cord components.

The way to "pierce through" the shadow DOM encapsulation is with CSS custom properties (also known as CSS variables). CSS custom properties are inherited from parent HTML element to its children, and this inheritance flow crosses through the shadow DOM.

For example, one custom property that the cord-thread component supports is --cord-thread-send-button-background-color--disabled. This property controls the color of the Send button when it is disabled (when the user has not started typing a message yet). If you want to change the color of the disabled Send button to be red in all cord-threads on your page, you can simply add the following CSS to your page:

cord-thread {
  --cord-thread-send-button-background-color--disabled: red;
}

The internal implementation of cord-thread looks very similar to:

.send-button:disabled {
  /* use the value of --cord-thread-send-button-background-color--disabled
  property or fall back to the default value if the property was not set */
  background-color: var(
    --cord-thread-send-button-background-color--disabled,
    some_fallback_value
  );
}

In the example above, you set the value of the property --cord-primary-button-background-color--disabled to red for cord-thread and all of its internal HTML elements. Inside the cord-thread, the Send button's background color is set to this value. If you had not set this value, then a fallback value would have been used instead.

You can easily change the color of the Send button when it is in any of its other states:

cord-thread {
  --cord-thread-send-button-background-color: black;
  --cord-thread-send-button-background-color--disabled: red;
  --cord-thread-send-button-background-color--hover: green;
  --cord-thread-send-button-background-color--active: blue;
}

We just saw how to change the color of the Send button. But what if you want to change the color of all buttons? Would you have to repeat the same process for all buttons? Fortunately, no. If you want to make all buttons red, you can use the property --cord-primary-button-background-color and add this CSS to your page:

/* change color of all primary buttons in cord-thread */
cord-thread {
  --cord-primary-button-background-color: red;
}

Alternatively, if you want to change all primary buttons in any Cord component on your page:

body {
  --cord-primary-button-background-color: red;
}

You might now be wondering what happens if you set both the --cord-primary-button-background-color and --cord-thread-send-button-background-color properties to different colors. What color would the Send button be? As you probably expect, it would be the color of --cord-thread-send-button-background-color because it is more specific. Above, we showed what the internal implementation of the Send button looks like, but a more accurate description is actually:

.send-button {
  background-color:
    /* value of this property is used if it was set */ 
    var(
      --cord-thread-send-button-background-color,
      /* otherwise the value of this property is used if it was set */ 
      var(--cord-primary-button-background-color, 
        /* if neither property is set, use this fallback value */
        fallback_value
      )
    );
}

The background color of the Send button is defined to be --cord-thread-send-button-background-color, with --cord-primary-button-background-color serving as fallback, with some other value (possibly another CSS property) as fallback if neither of the two CSS properties were set.

Finding the CSS property you need

There are several ways to find out what CSS properties are available to you:

• Consult the documentation page of the component you are using.
• Consult the reference for all CSS variables.
• If you have experience with your browser's developer tools, you can right click on the HTML element that you want to modify and choose Inspect. In the CSS section of the inspector, you can find which CSS properties are used to define the element's attributes.