Understanding Overrides

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:

  • Grab
    Item 1
  • Grab
    Item 2
  • Grab
    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 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',
},
},
}}
/>

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):

  • Grab
    Item 1
  • Grab
    Item 2
  • Grab
    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.accent400,
}),
},
}}
/>

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

  • Grab
    Item 1
  • Grab
    Item 2
  • Grab
    Item 3

Exploring Overrides

Almost every Base Web component has multiple overrides. How can you learn what's available to you? Every component page has the Style Overrides section at the top of the page. It lists all overridable subcomponents and highlights each one of them once activated. Using this editor, you can also change the style properties of each override, so you can see instantly how the modified components would look like.

If you are interested in which state props your style functions can use, you'll find the list of them by clicking the "Toggle shared props" button in the overrides:

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:

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:

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:

  • Grab
    Car
  • Grab
    Truck
  • Grab
    Bike
  • Grab
    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.