Styling

How to approach styling with Scale UI Radix.

Introduction

Scale UI Radix does not come with a built-in styling system. There’s no css or sx prop, and it does not use any styling libraries internally. Under the hood, it’s built with vanilla CSS.

There’s no overhead when it comes to picking a styling technology for your app, but in Scale we suggest to use Tailwind CSS for its utility-first approach and ergonomics.

What you get

The components in Scale UI Radix are relatively closed, they come with a set of styles that aren’t always easily overridden. They are customizable within what’s allowed by their props and the theme configuration. We also include semantic colors accent, neutral, error, info, warning and success along with all the colors supported by Radix Themes, you can see more in the color section.

However, you also get access to the same CSS variables that power the Scale UI Radix components, just have in mind that changes to the token system are treated as breaking.

For more information on specific tokens, refer to the corresponding guides in the Theme section or ask in the #scaleui-radix-design channel in Slack.

Overriding styles

Beyond simple style overrides, we recommend using the components as-is, or request new features or components so they can be included in the library.

Most components do have className and style props, but if you find yourself needing to override a lot of styles, it’s a good sign that you should either:

• Try to achieve what you need with the existing props and theme configuration.
• See whether you can achieve your design by tweaking the underlying token system.
• Check if the component you need is in the components roadmap and will be added in the future, if not you can request it in the Scale UI Radix channel in Slack.
• Reconsider whether Scale UI Radix is the right fit for your project. This library is intended to speed up the process of building interfaces, keep consistency and create a common language across the Scale ecosystem. If you need a lot of custom styling, you might be better off using a different library or building your own components.

Common issues

z-index conflicts

Out of the box, portalled Radix Themes components can be nested and stacked in any order without conflicts. For example, you can open a popover that opens a dialog, which in turn opens another popover. They all stack on top of each other in the order they were opened:

When building your own components, use the following rules to avoid z-index conflicts:

• Don’t use z-index values other than auto, 0, or -1 in rare cases.
• Render the elements that should stack on top of each other in portals.

Your main content and portalled content are separated by the stacking context that the styles of the root <Theme> component create. This allows you to stack portalled content on top of the main content without worrying about z-indices.

Next.js import order

As of Next.js 13.0 to 14.1, the import order of CSS files in app/**/layout.tsx is not guaranteed, so Radix Themes may overwrite your own styles even when written correctly:

import '@radix-ui/themes/styles.css';
import './my-styles.css';

This Next.js issue may come and go sporadically, or happen only in development or production.

As a workaround, you can merge all the CSS into a single file first via postcss-import and import just that into your layout. Alternatively, importing the styles directly in page.tsx files also works.

Missing styles in portals

When you render a custom portal in a Radix Themes project, it will naturally appear outside of the root <Theme> component, which means it won’t have access to most of the theme tokens and styles. To fix that, wrap the portal content with another <Theme>:

// Implementation example of a custom dialog using the low-level Dialog primitive
// Refer to https://www.radix-ui.com/primitives/docs/components/dialog
import * as Dialog from '@radix-ui/react-dialog';
import { Theme } from '@scale/scaleui-radix';

function MyCustomDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open</Dialog.Trigger>
      <Dialog.Portal>
        <Theme>
          <Dialog.Overlay />
          <Dialog.Content>
            <Dialog.Title />
            <Dialog.Description />
            <Dialog.Close />
          </Dialog.Content>
        </Theme>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Components like Dialog and Popover in Radix Themes already handle this for you, so this is only necessary when creating your own portalled components.