StylingCDS includes powerful and flexible APIs for styling components. Easily access values from the theme, or go rogue with full customization.

󰏖

View as Markdown

StyleProps API

Most components support the StyleProps API. StyleProps automatically have access to the values in the theme, and some StyleProps are limited to only the theme values.

See the full list of StyleProps here →

// ✅ The `bgNegative` token will automatically update with the theme!
<Box background="bgNegative" width={100} />

// ❌ Error: Type '"#0000ff"' is not assignable to type 'Color | undefined'.
<Box background="#0000ff" width={100} />

󰔂

Tip

The docs page of every component has a props table listing all the available props!

󰔂

Note

The StyleProps API applies static atomic classnames under the hood. These classnames reference CSS Variables set by the ThemeProvider to enable dynamic theming.

---

Responsive styles

On web, all StyleProps support an optional responsive syntax for device-specific styles.

<Box
  width={{ base: 200, tablet: 200, desktop: 400 }}
  background={{ base: 'bgPrimary', phone: 'bgSecondary' }}
/>

• base: no media query
• phone: (max-width: 767px)
• tablet: (min-width: 768px) and (max-width: 1279px)
• desktop: (min-width: 1280px)

It is not possible to customize the breakpoint values unless you compile CDS from the source code.

Import the media object to use CDS breakpoints and media queries in your own custom styles.

See how breakpoints are defined in the media object →

import styled from 'styled-components';
import { media } from '@coinbase/cds-web/styles/media';

const MyCustomThing = styled.div`
  ${media.phone} {
    width: 100px;
  }
`;

---

Selectors

Some complex components have multiple internal elements that can be styled individually. CDS provides several ways to target these elements using selectors. The same selector keys (like root, content, etc.) are reused across styles, classNames, and static class names, giving you flexibility in how you apply custom styles.

󰔂

Tip

Components that support selectors have a Styles tab in their documentation listing all available selectors. Check out NavigationBar for an example.

---

style and styles props

Most components support the native style prop for inline styles.

<Box style={{ backgroundColor: '#0000ff' }} />

Some complex components support passing inline styles to subcomponents with the styles prop. The keys correspond to the component's internal selectors.

<ProgressCircle
  styles={{
    circle: {
      stroke: 'transparent',
    },
    progress: {
      strokeLinecap: 'square',
    },
  }}
  color="fgPositive"
  progress={0.75}
  size={100}
/>

Styles are merged together as objects in order of specificity.

<PageHeader style={{ backgroundColor: 'red' }} styles={{ root: { backgroundColor: 'blue' } }} />

In the example above, backgroundColor will be blue.

---

className and classNames props

Most components support the native className prop for adding custom class names.

<Box className="my-custom-box" />

Some complex components support passing class names to subcomponents with the classNames prop. The keys correspond to the component's internal selectors.

<ProgressCircle
  classNames={{
    circle: 'my-custom-circle',
    progress: 'my-custom-progress',
  }}
  color="fgPositive"
  progress={0.75}
  size={100}
/>

---

Static class names

Components also expose static CSS class names for their internal elements, allowing you to target them directly with CSS selectors without using props. These class names follow the pattern cds-{ComponentName} for the root element and cds-{ComponentName}-{part} for sub-elements.

/* Target the NavigationBar root */
.cds-NavigationBar {
  background-color: #f5f5f5;
}

/* Target a specific part */
.cds-NavigationBar-start {
  padding-left: 16px;
}

Static class names are useful when you need to:

• Apply styles from a global stylesheet or CSS file
• Target elements in CSS-in-JS solutions like styled-components
• Override styles in specific contexts (e.g., when a component is inside another component)
• Apply styles that aren't available through StyleProps

---

Component specific props

Many components have their own specific props that can affect styling.

<Button compact variant="primary">
  Click me
</Button>

---

Combining techniques

Mix and match these styling techniques for complete customization!

<Button variant="primary" borderColor="accentBoldPurple" style={{ fontFamily: 'Times' }}>
  Click me
</Button>

---

Global CSS reset

CDS web global styles include a CSS reset which override the browser default styles for some elements. This ensures that polymorphic components render correctly, regardless of their HTML element.

See the global CSS reset here →

---

Polymorphic components

Many CDS web components have the polymorphic as prop, which allows you to change what component or element is being rendered under the hood.

Using the polymorphic as prop will change the component's type to allow the relevant native props.

<Button as="a" href="google.com" />
<Link as="button" type="submit" />

---