Developer Customization

Customers maintain full control over the style and layout of their site without needing access to the library’s source code. The entire library is customizable from their own repository, with options detailed below.

Structural changes

Think of the libraries as configurable building blocks. They come with sensible defaults but are arranged within each client’s repository, allowing custom configurations to override those defaults.

The library makes only a few assumptions about implementation, which are specified in the client repository, including site structure, page names, and navigation setup. These are mostly dependent on client preferences and require minimal coding.

Below is an example of a typical library implementation. Notice that all client-specific dependencies are passed as properties. For example, NavBar  and SideMenu  are standard components. By rearranging or adding new components, you can easily customize the page structure.

Additionally, observe the sideBarContent  being passed. Most components in the library come with default children, but these defaults can be overridden. The component used for overriding can originate from the client’s repository, and there are no restrictions on which components can be passed as overrides.

Theme changes (global styling)

We use MUI (https://mui.com/) as our styling framework. MUI provides extensibility and clean default styling, making it ideal for Shapeshift’s flexible architecture.

Clients can override these defaults through a theme object maintained in their repository. This theme is passed into a ThemeProvider  at the root level. Using this, developers can customize global properties such as:

  • Component styles
  • Color palettes
  • Typography
  • Media query breakpoints
Default theme customization and declaration
Theme provider declaration

Component styling

Components within the common library can be customized in multiple ways. The recommended approach is class name overrides.

Class name overrides

All components are styled using TSS, which generates HTML with unique class names to prevent conflicts. Clients can override these class names within their own repository using CSS selectors.

For example, you can modify the background of a pageBase  component to white. Class names can be inspected using browser tools such as Chrome’s Inspect Element.

  • Names without scope identifiers are stable and safe to use.
  • Names with scope identifiers (for example mui-65kn6v- ) are automatically generated but still usable if clearly identified.

Class names specified in the client repository take precedence over those in the component itself. However, inline styles applied in the client repository will override all other styles.

When inspecting the source via Chrome, class names such as mui-65kn6v-background  may appear. The segment background  is stable and safe to use for targeting specific elements without affecting other components.

SX or style prop

Both the sx  prop and the standard style  prop can be used for inline styling.

  • sx  (specific to MUI) offers enhanced styling capabilities.
  • Inline styles always take precedence, ensuring your overrides render as intended.

Learn more about the sx  prop in the MUI documentation.

style prop override
sx prop override

Data overrides

Many components in the Shapeshift libraries handle API communication automatically. However, you may wish to call your own API or modify the data before it is passed to a component. This is where data overrides come in.

Below is an example of modifying the API response for courses. All Shapeshift endpoints can be queried via hooks or data providers.

In this example, the courses  data provider is used. It’s simple to wrap a component with a provider to give it API access, even for completely custom components maintained in the client repository.

In this case, the data is altered to prefix “The best” before every course title, but any transformation can be applied as long as the TypeScript definitions remain valid.

Action overrides

Library components may contain internal actions. Some are specific to Shapeshift (for example onCompleteModule ), while others are standard actions such as onClick .

Shapeshift is designed to extend functionality, not limit it. For example, the OutlineButton  component can be customized while retaining its full accessibility and behavior.

Shapeshift-specific functionality begins with actionOverride . For instance, actionOverrideDownload  in the File component prevents the default behavior, allowing developers to inject custom logic using the same parameters as the original action.