Understanding Overrides

By the end of this guide, you'll learn the concept of overrides in Base Web, and the ways you can use them to change the look or the behavior of components.

Base Web is a set of reusable React components that implements the Base Web design language and can be used in two different ways:

To build an application that fully adopts the Base Web design language, you import and use Base Web components out of the box.
To build a new design system inherited from the Base, you take Base Web components and customize them through the Overrides mechanism.

If you are building an application using the Base Web design language (the first scenario), you should avoid further customization. This helps to keep the design of your application consistent and makes future upgrades easier. Overrides is an escape hatch that should be used only with the great caution!

Subcomponents

Base Web components typically consist of many subcomponents. Let's use baseui/dnd-list as an example:

Item 1
Item 2
Item 3

This component is very self-contained and you can load it through a single import:

import {StatefulList} from 'baseui/dnd-list';
export default () => (
  <StatefulList
    initialState={{
      items: ['Item 1', 'Item 2', 'Item 3'],
    }}
  />
);

But as you might guess, there are multiple React components under the hood, components like Item, DragHandle or Label. They all come with various styles, behaviors and attributes. We call them subcomponents.

Introducing Overrides

Overrides gives you a full access to all those subcomponents and lets you to override:

styles of the subcomponent
props of the subcomponent
the whole subcomponent

Every Base Web component has a top-level prop called overrides. It accepts a map of subcomponents and desired overrides. For example, if we want to change the Label's color and also add an additional data-test-id attribute (props are spread over the subcomponent), we can do:

<StatefulList
  initialState={{
    items: ['Item 1', 'Item 2', 'Item 3'],
  }}
  overrides={{
    Label: {
      style: {
        color: '#892C21',
      },
      props: {
        'data-test-id': 'dnd-list-label',
      },
    },
  }}
/>

Overrides for style, component and props can be passed as functions too. For example, the overrides below are valid and equivalent.

<Component
  active
  overrides={{
    props: { 'data-test': props.active ? 'foo-active' : 'foo' }
  }}
/>
<Component
  active
  overrides={{
    props: props => ({ 'data-test': props.active ? 'foo-active' : 'foo' })
  }}
/>

We defined overrides.Label.style and overrides.Label.props properties and this is the result (inspect the element to see the data-test-id attribute):

Item 1
Item 2
Item 3

The overrides.Label.style property accepts a style object or style function since Styletron manages all Base Web styles.

Caveat: When using overrides.foo.style, you are overriding a set of existing CSS properties. Our components always use longhand CSS properties and so should yours! If you mix shorthand and longhand properties, you will see a warning and can run into strange behaviors!

`$theme`

If you opt-in for the style function, overrides provides a special prop called $theme that you can use. The $theme prop includes all Base Web design constants. So instead of the hard-coded value #892C21, you can use the theme:

<StatefulList
  initialState={{
    items: ['Item 1', 'Item 2', 'Item 3'],
  }}
  overrides={{
    Label: {
      style: ({$theme}) => ({
        color: $theme.colors.negative600,
      }),
    },
  }}
/>

State Props

The prop $theme is not the only variable that you can use in your style function. Most of subcomponents get various state props. For example, the Label comes with:

$isDragged: boolean - true if the list item is dragged
$isSelected: boolean - true if the list item is selected (space key-press)
$isRemovable: boolean - true if the list item is removable
$value: React.Node - item's value
$index: number - item's index

Let's use $isDragged to change the Label color when dragged:

<StatefulList
  initialState={{
    items: ['Item 1', 'Item 2', 'Item 3'],
  }}
  overrides={{
    Label: {
      style: ({$theme, $isDragged}) => ({
        color: $isDragged ? $theme.colors.primary : $theme.colors.negative600,
      }),
    },
  }}
/>

The result is that the Label turns blue when it's dragged:

Item 1
Item 2
Item 3

Overrides Inspector

Almost every Base Web component has multiple overrides. How can you learn what's available to you? Every component page has the Overrides section at the bottom. It lists all overridable subcomponents and highlights each one of them. This section is taken straight from the dnd-list page:

Additionally, you can fully customize any part of the Drag and Drop List through the overrides prop. The Drag and Drop List consists of multiple subcomponents that are listed bellow and you can override each one of them. To help you identify the names of these subcomponents, you can highlight them through this selector:

Item 1
Item 2
Item 3
Item 4

Note: You should always use longhand CSS properties. Mixing shorthands and longhands will lead into strange behaviors!

If you are interested in which state props your style functions can use, you'll find the list of them at the bottom of every component page. Scroll down to the API section and click on the Expand Prop Shape button for the overrides property.

Override Nested Components

Every Base Web component exposes the override prop. When one Base Web component uses another Base Web component internally we have access to a new, powerful pattern: Nested Overrides.

The idea is to use a component's overrides prop to access a nested component and pass this nested component an overrides prop of its own. You end up with a nested structure like so:

<Foo
  overrides={{
    Boo: {
      props: {
        overrides: {
          // pass "nested" overrides to the inner "Boo" component
        },
      },
    },
  }}
/>

This is a very reliable method for customizing deeply nested components. It is possible because everywhere a Base Web component uses another Base Web component, that ‟parent” component will expose an overrides property for the ‟child” component. In theory, you could nest overrides as many levels deep as necessary to customize something.

<Foo
  overrides={{
    Boo: {
      props: {
        overrides: {
          Moo: {
            props: {
              overrides: {
                Zoo: {
                  props: {
                    overrides: {
                      Goo: () => 'hey mom!',
                    },
                  },
                },
              },
            },
          },
        },
      },
    },
  }}
/>

In this example, we use four nested overrides to replace the Goo component. We do this without affecting the four components above Goo. We've avoided having to re-implement layers and layers of logic, and, because the interface is consistent, you can focus on where you want to drop in, rather than how to do it.

If you find the exact syntax of this technique a little difficult to recall, try instead to remember that every Base Web component exposes an overrides prop and that every nested Base Web component is made accessible as an overrides property in the top-level component.

The path always follows this pattern:

ComponentA > overrides > ComponentB > props > overrides

A more practical example

Here is the default multi-select option for Base Web:

Atlanta

Let's change the way the selected values appear.

The first step is to identify what we want to override. In this case, we want to change the selected values for a multi-select. Let's check out the overrides inspector for Select. Looking through the list of possible overrides, we see there is a promising MultiValue property.

You might notice that the MultiValue component is just an instance of the Tag component. We can reference the documentation for Tag to see what overrides are available.

We have identified a nested Base Web component that is accessible via overrides. Now we can apply some nested overrides to customize things:

Atlanta

Notice the nested override pattern here:

StatefulSelect > overrides > MultiValue > props > overrides

Once we have access to the nested Tag, we can override the styles for the Root, Text, Action & ActionIcon, changing the colors to a few lovely shades of purple.

Override The Entire Subcomponent

This is a very advanced technique and rarely needed. If you go down this path, you might also need to inspect our source code to fully understand all behaviors that subcomponents should/can implement.

So far we demonstrated how to override styles or add additional props but you can also completely replace subcomponents. This means you can alter the behavior and appearance of all Base Web components. For example, we can enhance our textual Label and add a cloning functionality:

import * as React from 'react';
import {List, arrayMove} from 'baseui/dnd-list';
export default class Example extends React.Component {
  state = {
    items: ['Car', 'Truck', 'Bike', 'Skateboard'],
  };
  render() {
    return (
      <List
        items={this.state.items}
        onChange={({oldIndex, newIndex}) =>
          this.setState(prevState => ({
            items: arrayMove(prevState.items, oldIndex, newIndex),
          }))
        }
        overrides={{
          Label: {
            component: ({$value}) => (
              <div style={{flexGrow: 1}}>
                {$value}{' '}
                <button
                  onClick={() =>
                    this.setState(prevState => ({
                      items: prevState.items.concat([`${$value} clone`]),
                    }))
                  }
                >
                  Clone
                </button>
              </div>
            ),
          },
        }}
      />
    );
  }
}

The result:

Car
Truck
Bike
Skateboard

Note that we lost the original Label styling since we replaced the whole Label subcomponent. If you still want to reuse or compose the original subcomponent you can import it:

import {StyledLabel} from 'baseui/dnd-list';

The named import always matches the override key with an addition of Styled prefix. Following two examples yield the exactly same result since this is how Base Web components are implemented underneath:

<StatefulList
  initialState={{items: ['A', 'B', 'C']}}
  overrides={{Label: StyledLabel}}
/>
<StatefulList
  initialState={{items: ['A', 'B', 'C']}}
/>

This technique gives you a ridiculous amount of flexibility. However, with great power comes great responsibility. We might not be able to effectively support you if you run into issues and upgrades to future versions of Base Web can be complicated. If you have a need to change components behavior this way, you should first ask maintainers of Base Web. We might add your feature through an official API instead so you don't need to use this override.

To learn more about how overrides work internally, check out the Better Reusable React Components with the Overrides Pattern article.