Circuit UI

https://github.com/sumup-oss/circuit-ui
Admin
Circuit UI is the React component library that implements SumUp's Circuit Design System, enabling...
Tokens:61,776
Snippets:1,060
Trust Score:9.1
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install @sumup-oss/icons

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/icons/README.md

Commands to install the package using npm or yarn.

```sh
# With npm
npm install @sumup-oss/icons

# With yarn v1
yarn add @sumup-oss/icons
```

--------------------------------

### Install the package

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/illustrations/README.md

Use npm or yarn to add the package to your project.

```sh
# With npm
npm install @sumup-oss/illustrations

# With yarn
yarn add @sumup-oss/illustrations
```

--------------------------------

### Run the development server

Source: https://github.com/sumup-oss/circuit-ui/blob/main/templates/nextjs/template/README.md

Starts the local development server for the Next.js application.

```bash
npm run dev
```

--------------------------------

### Install peer dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/introduction/2-getting-started.mdx

Install the required peer dependencies for Circuit UI to function correctly.

```sh
# With npm:
npm install --save @sumup-oss/design-tokens @sumup-oss/icons @sumup-oss/intl react react-dom temporal-polyfill
# With yarn v1
yarn add @sumup-oss/design-tokens @sumup-oss/icons @sumup-oss/intl react react-dom temporal-polyfill
```

--------------------------------

### Install a specific release channel version

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/contributing/4-release-process.mdx

Use this command to install a version from a specific release channel in your project.

```bash
npm install @sumup-oss/circuit-ui@<release-channel>
```

--------------------------------

### Design token migration example

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Example of manual migration for typography design tokens.

```text
typography.text.mega
```

```text
typography.body.one
```

--------------------------------

### Install Peer Dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/README.md

Install the necessary peer dependencies if they are not already present in your project.

```sh
# With npm
npm install --save react react-dom @sumup-oss/design-tokens @sumup-oss/icons @sumup-oss/intl
# With yarn v1
yarn add react react-dom @sumup-oss/design-tokens @sumup-oss/icons @sumup-oss/intl
```

--------------------------------

### Install Circuit UI

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/README.md

Use these commands to add the library to your project using npm or yarn.

```sh
# With npm
npm install --save @sumup-oss/circuit-ui
# With yarn v1
yarn add @sumup-oss/circuit-ui
```

--------------------------------

### Modal Provider Setup

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/Modal/Modal.mdx

Wrap the application in a ModalProvider to enable the useModal hook.

```tsx
import { ModalProvider } from '@sumup-oss/circuit-ui';

export function App() {
  return <ModalProvider>{/* Your content here... */}</ModalProvider>;
}
```

--------------------------------

### Install core peer dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Install required React and Emotion peer dependencies for Circuit UI v2.

```sh
# With yarn
yarn add react react-dom @emotion/core @emotion/styled emotion-theming
# With npm
npm install --save react-dom @emotion/core @emotion/styled emotion-theming
```

--------------------------------

### Install the ESLint plugin

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/README.md

Use npm or yarn to add the package as a development dependency.

```sh
# With npm
npm install --save-dev @sumup-oss/eslint-plugin-circuit-ui

# With yarn v1
yarn add --dev @sumup-oss/eslint-plugin-circuit-ui
```

--------------------------------

### Install design tokens package

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/design-tokens/README.md

Use npm or yarn to add the package to your project dependencies.

```sh
# With npm
npm install @sumup-oss/design-tokens

# With yarn v1
yarn add @sumup-oss/design-tokens
```

--------------------------------

### Install Circuit UI package

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/introduction/2-getting-started.mdx

Use npm or yarn to add the Circuit UI package to an existing project.

```sh
# With npm:
npm install @sumup-oss/circuit-ui

# With yarn v1
yarn add @sumup-oss/circuit-ui
```

--------------------------------

### Install extracted package dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Install the new required peer dependency packages for themes, icons, internationalization, and event tracking.

```sh
# With yarn
yarn add @sumup/collector @sumup/design-tokens @sumup/icons @sumup/intl
# With npm
npm install --save @sumup/collector @sumup/design-tokens @sumup/icons @sumup/intl
```

--------------------------------

### Correct component usage

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-renamed-components/README.md

Example of the updated component import and usage after applying the rule.

```tsx
import { ActionMenu } from '@sumup-oss/circuit-ui/components/ActionMenu';

function Component() {
  return <ActionMenu isOpen={true} />;
}
```

--------------------------------

### Correct usage of props

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-deprecated-props/README.md

This example shows the recommended way to use the component after replacing the deprecated prop.

```tsx
function Component() {
  return <Body color="danger" />;
}
```

--------------------------------

### Incorrect component imports

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/component-lifecycle-imports/README.md

Shows an example of importing components from the experimental entrypoint when they have moved to the stable entrypoint.

```tsx
import { Timestamp } from '@sumup-oss/circuit-ui/experimental';
import type { TimestampProps } from '@sumup-oss/circuit-ui/experimental';
```

--------------------------------

### Use legacy styled component

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Example of a component using the custom styled utility.

```tsx
// components/RedCard.tsx
import { css } from "@emotion/core";

import styled from "util/styled";

const RedCard = styled(Card)(
  ({ theme }) => css`
    background-color: red;
  `
);
```

--------------------------------

### Spacing Mixin Usage

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/styles/style-mixins.mdx

Examples of applying spacing to elements.

```tsx
// A single spacing string is applied to all sides
const AllSides = () => <div css={spacing('kilo')} />;

// Specify spacing for individual sides in an object
const IndividualSides = () => (
  <div
    css={spacing({ top: 'kilo', right: 'mega', left: 'giga', bottom: 'kilo' })}
  />
);

// The `spacing` mixin supports the special values `0` and `auto`,
// this can be useful to horizontally center an element
const HorizontallyCentered = () => (
  <div css={spacing({ left: 'auto', right: 'auto' })} />
);
```

--------------------------------

### Typography component size mapping

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Examples of mapping v2 typography component sizes to v3 equivalents.

```jsx
<Heading size="kilo">
```

```jsx
<Headline size="four">
```

```jsx
<Heading size="mega">
```

```jsx
<Headline size="four">
```

```jsx
<Heading size="giga">
```

```jsx
<Headline size="three">
```

```jsx
<Heading size="tera">
```

```jsx
<Headline size="two">
```

```jsx
<Heading size="peta">
```

```jsx
<Headline size="one">
```

```jsx
<Heading size="exa">
```

```jsx
<Headline size="one">
```

```jsx
<Heading size="zetta">
```

```jsx
<SubHeading size="kilo">
```

```jsx
<SubHeadline>
```

```jsx
<SubHeading size="mega">
```

```jsx
<SubHeadline>
```

```jsx
<Text size="kilo">
```

```jsx
<Body size="two">
```

```jsx
<Text size="mega">
```

```jsx
<Body size="one">
```

```jsx
<Text size="giga">
```

--------------------------------

### Update Emotion dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Remove legacy Emotion packages and install the v11 equivalents.

```sh
# example with yarn
yarn remove @emotion/core jest-emotion babel-plugin-emotion # remove legacy dependencies
yarn add @emotion/react # add new dependencies
yarn add -D @emotion/babel-plugin @emotion/jest # add new dev dependencies
yarn upgrade @emotion/styled --latest # upgrade existing packages
```

--------------------------------

### Correct usage of default props

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-default-props/README.md

Examples of code that comply with the rule by omitting redundant props.

```jsx
import { Body, Button, IconButton } from '@sumup-oss/circuit-ui';

<Body>Hello</Body>;
<Button>Submit</Button>;
<IconButton icon={More}>More</IconButton>;
```

--------------------------------

### Structure two-dimensional data with HTML tables

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/List/List.mdx

An example of using an HTML table to display country and capital data for better accessibility.

```html
<table>
  <tr>
    <th>Country</th>
    <th>Capital</th>
  </tr>
  <tr>
    <td>Germany</td>
    <td>Berlin</td>
  </tr>
  <tr>
    <td>Ireland</td>
    <td>Dublin</td>
  </tr>
  <tr>
    <td>Canada</td>
    <td>Ottawa</td>
  </tr>
</table>
```

--------------------------------

### Badge to Status rename example

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-renamed-components/README.md

Demonstrates the transformation of the Badge component to the Status component.

```tsx
import { Badge } from '@sumup-oss/circuit-ui';

function Component() {
  return <Badge variant="danger">1</Badge>;
}
```

```tsx
import { Status } from '@sumup-oss/circuit-ui';

function Component() {
  return <Status variant="danger">1</Status>;
}
```

--------------------------------

### Structure two-dimensional data with HTML lists

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/List/List.mdx

An example of using a standard unordered list to display country and capital data.

```html
<ul>
  <li>Germany (Capital: Berlin)</li>
  <li>Ireland (Capital: Dublin)</li>
  <li>Canada (Capital: Ottawa)</li>
</ul>
```

--------------------------------

### Correct usage of updated custom properties

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-deprecated-custom-properties/README.md

This example shows the compliant version of the CSS code using the current design tokens.

```css
.class {
  font-size: var(--cui-typography-headline-l-font-size);
  line-height: var(--cui-typography-headline-l-line-height);
}
```

--------------------------------

### SVG Icon Implementation

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/icons/CONTRIBUTING.md

Example of an SVG icon structure, noting that brand icons should use specific fill colors rather than currentColor.

```svg
<svg width="32" height="24" viewBox="0 0 32 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect x="0.5" y="0.5" width="31" height="23" rx="3.5" fill="white" stroke="#CCCCCC"/><!-- Note that this isn't currentColor because this is a brand icon -->
<path d="M20.1117 4C18.5512 3.99926 17.0261 4.46404 15.7312 5.3349C15.6421 5.39584 15.026 5.83591 14.9989 5.85735C13.9754 6.62692 13.2882 6.76008 12.3471 6.52424C12.2896 6.50957 12.0199 6.41704 11.9353 6.38432C11.0563 6.05338 10.1107 5.93826 9.17805 6.04865C8.24536 6.15903 7.35279 6.4917 6.57536 7.01868C5.79794 7.54566 5.15837 8.25156 4.71041 9.07705C4.26246 9.90255 4.0192 10.8235 4.00109 11.7625C3.98298 12.7016 4.19055 13.6312 4.60634 14.4734C5.02214 15.3155 5.63401 16.0456 6.39054 16.6021C7.14707 17.1587 8.02615 17.5255 8.95389 17.6718C9.88163 17.8181 10.8309 17.7395 11.722 17.4427C13.1257 17.0229 13.8874 17.138 14.7687 17.7598C14.9447 17.8839 15.369 18.1558 15.457 18.2201C16.4601 18.9562 17.6233 19.444 18.8513 19.6437C20.0793 19.8434 21.3371 19.7492 22.5217 19.3688C23.7062 18.9884 24.7838 18.3328 25.666 17.4555C26.5482 16.5783 27.2099 15.5044 27.597 14.322C27.984 13.1396 28.0853 11.8823 27.8926 10.6532C27.6998 9.42413 27.2185 8.25819 26.4882 7.25102C25.7578 6.24385 24.7991 5.4241 23.6907 4.859C22.5823 4.2939 21.3558 3.99952 20.1117 4V4Z" fill="#007858"/>
<path d="M17.2712 13.0904C17.0471 13.311 16.7549 13.4491 16.4422 13.4823C16.1295 13.5155 15.8147 13.4418 15.5493 13.2732L15.0268 14.1026C15.4795 14.3886 16.0155 14.5135 16.5479 14.4569C17.0804 14.4004 17.5782 14.1658 17.9607 13.7911L17.2712 13.0904ZM16.3302 9.71194C15.8986 9.70508 15.4734 9.81575 15.1 10.0321C14.7265 10.2484 14.419 10.5623 14.2103 10.94C14.0016 11.3178 13.8996 11.7452 13.9152 12.1764C13.9309 12.6077 14.0635 13.0266 14.299 13.3883L18.6073 11.5467C18.486 11.0311 18.1962 10.5706 17.7838 10.2383C17.3713 9.90597 16.8598 9.72073 16.3302 9.71194V9.71194ZM14.9027 12.2373C14.8701 11.9393 14.9342 11.6387 15.0855 11.3799C15.2368 11.121 15.4673 10.9177 15.7429 10.7998C16.0186 10.682 16.3248 10.6559 16.6165 10.7253C16.9081 10.7948 17.1697 10.9562 17.3626 11.1856L14.9027 12.2373ZM19.9602 8.64108V13.2326L20.7569 13.5632L20.3811 14.4659L19.5912 14.1387C19.4322 14.0706 19.297 13.9567 19.2031 13.8114C19.0981 13.6423 19.0451 13.4462 19.0507 13.2472V8.64108H19.9602ZM13.0228 8.64108V13.2326L13.8127 13.5632L13.4369 14.4659L12.647 14.1387C12.4933 14.0701 12.3628 13.9584 12.2713 13.8171C12.1659 13.6481 12.1126 13.4519 12.1178 13.2529V8.64108H13.0228Z" fill="white"/>
<path d="M23.88 10.828C24.0456 10.9078 24.1938 11.0195 24.3162 11.1567C24.4385 11.2938 24.5327 11.4537 24.5933 11.6272C24.6538 11.8007 24.6796 11.9845 24.6691 12.168C24.6587 12.3515 24.6122 12.5311 24.5323 12.6966L25.4135 13.1198C25.6521 12.6223 25.7103 12.0573 25.5781 11.5217C25.446 10.986 25.1317 10.5129 24.6892 10.1834C24.2466 9.85392 23.7033 9.68853 23.1522 9.71555C22.6011 9.74257 22.0766 9.96031 21.6684 10.3315L22.3274 11.0548C22.5338 10.866 22.7921 10.7435 23.0689 10.703C23.3457 10.6626 23.6282 10.7061 23.88 10.828V10.828Z" fill="#C7D540"/>
<path d="M22.6667 13.3522C22.3322 13.1911 22.0753 12.9039 21.9523 12.5535C21.8294 12.2032 21.8505 11.8184 22.0111 11.4836L21.1298 11.0593C20.8936 11.5562 20.8369 12.1195 20.9694 12.6535C21.1019 13.1874 21.4154 13.6589 21.8565 13.9877C22.2976 14.3165 22.839 14.4822 23.3885 14.4567C23.9381 14.4311 24.4618 14.2159 24.8705 13.8476L24.2115 13.1254C24.0056 13.3123 23.7487 13.4337 23.4736 13.4741C23.1985 13.5145 22.9176 13.4721 22.6667 13.3522V13.3522ZM11.2168 13.4188V12.0895C11.2168 11.6209 11.0778 11.1627 10.8174 10.773C10.557 10.3834 10.1869 10.0796 9.75394 9.90027C9.32095 9.72092 8.84449 9.67399 8.38482 9.76543C7.92516 9.85686 7.50293 10.0825 7.17153 10.4139C6.84012 10.7454 6.61444 11.1676 6.523 11.6272C6.43157 12.0869 6.4785 12.5634 6.65785 12.9964C6.8372 13.4294 7.14093 13.7995 7.53061 14.0598C7.9203 14.3202 8.37845 14.4592 8.84712 14.4592C9.21449 14.4592 9.57685 14.3739 9.90556 14.2098L9.52416 13.3184C9.31062 13.4365 9.06995 13.4967 8.82596 13.4932C8.58197 13.4898 8.34312 13.4226 8.13304 13.2985C7.92296 13.1744 7.74893 12.9975 7.62817 12.7855C7.50741 12.5734 7.4441 12.3336 7.44451 12.0895C7.44324 11.8603 7.49867 11.6343 7.60588 11.4317C7.70023 11.2549 7.83131 11.1002 7.99031 10.9782C8.14931 10.8562 8.33256 10.7696 8.52778 10.7242C8.63132 10.6997 8.73733 10.6872 8.84373 10.6869C9.21613 10.6866 9.57341 10.8342 9.83705 11.0972C10.1007 11.3602 10.2491 11.7171 10.2497 12.0895V13.4075C10.2441 13.6064 10.2971 13.8026 10.4021 13.9717C10.4967 14.1164 10.6316 14.2301 10.7902 14.299L11.2348 14.475L11.6117 13.5723L11.2168 13.4188Z" fill="white"/>
</svg>
```

--------------------------------

### Correct usage of icons

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-deprecated-icons/README.md

Example of code that complies with the rule by using a valid, non-deprecated icon.

```tsx
import { FlagFr } from '@sumup-oss/icons';
function Component() {
  return <FlagFr />
}
```

--------------------------------

### Define a metadata description list

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/List/List.mdx

A simple example of a description list containing two metadata label-value pairs.

```html
<dl>
  <dt>Account number</dt>
  <dd>12345</dd>
  <dt>Sign-up date</dt>
  <dd>21.12.2021</dd>
</dl>
```

--------------------------------

### Correct usage of custom properties

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-invalid-custom-properties/README.md

Example of a valid CSS custom property usage that complies with the rule.

```css
color: var(--cui-bg-normal);
```

--------------------------------

### Correct usage of renamed props

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-renamed-props/README.md

Examples of code that comply with the current Circuit UI prop naming conventions.

```tsx
// Since Circuit UI v9
function Component() {
  return (
    <div>
      <Display size="l" />
      <Headline size="m" />
      <Body size="s" />
    </div>
  );
}

// Since Circuit UI v7.5
function Component() {
  return (
    <div>
      <Avatar size="s" />
      <Hamburger size="s" />
      <ProgressBar size="s" />
      <SelectorGroup size="s" />
      <Spinner size="s" />
      <Button size="s" />
      <IconButton size="s" icon={Add}>
        Add to card
      </IconButton>
    </div>
  );
}

// Badge → Status
function Component() {
  return (
    <Badge color="alert" variant="badge">
      1
    </Badge>
  );
}
```

--------------------------------

### Update package dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Uninstall old @sumup packages and install the new @sumup-oss scoped packages along with required peer dependencies.

```sh
npm uninstall @sumup/circuit-ui @sumup/design-tokens @sumup/icons @sumup/intl
npm install @sumup-oss/circuit-ui @sumup-oss/design-tokens @sumup-oss/icons @sumup-oss/intl temporal-polyfill
```

--------------------------------

### Initialize a new project

Source: https://github.com/sumup-oss/circuit-ui/blob/main/templates/astro/README.md

Use this command to scaffold a new Astro project using the Circuit UI template.

```bash
npx create-astro@latest ./my-app --template sumup-oss/circuit-ui/templates/astro
```

--------------------------------

### Run Circuit UI Migration CLI

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Displays the help menu and available options for the migration CLI tool.

```sh
yarn circuit-ui migrate

Automatically transforms your source code to Circuit UI's latest APIs

Options:
  --language, -l   The programming language(s) of the files to be transformed
                [array] [required] [choices: "TypeScript", "JavaScript", "Flow"]
  --path, -p       A path to the folder that contains the files to be
                   transformed                           [string] [default: "."]
  --transform, -t  The transform to be applied to the source code
                       [string] [required] [choices: "button-variant-enum", ...]
```

--------------------------------

### Enter prerelease mode

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/contributing/4-release-process.mdx

Commands to switch to a release branch and initialize prerelease mode using changesets.

```bash
git checkout next # or `canary`
npx changeset pre enter next # or `canary`
```

--------------------------------

### Build the icons package

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/icons/CONTRIBUTING.md

Build the icons package using lerna.

```bash
npx lerna run build --scope=@sumup-oss/icons
```

--------------------------------

### Configure the plugin

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/stylelint-plugin-circuit-ui/README.md

Add the plugin to your Stylelint configuration file.

```json
{
  "plugins": ["@sumup-oss/stylelint-plugin-circuit-ui"]
}
```

--------------------------------

### Incorrect component usage

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-renamed-components/README.md

Example of an outdated component import and usage that triggers the rule.

```tsx
import { Popover } from '@sumup-oss/circuit-ui';

function Component() {
  return <Popover isOpen={true} />;
}
```

--------------------------------

### Upgrade dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Run this command to update the core library and design tokens to the latest version.

```sh
npm upgrade @sumup/circuit-ui @sumup/design-tokens @sumup/icons
```

--------------------------------

### Initialize ToastProvider

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/NotificationToast/NotificationToast.mdx

Wrap the application in ToastProvider to manage toast state and ensure accessibility.

```tsx
// _app.tsx for Next.js or App.js for CRA
import { ToastProvider } from '@sumup-oss/circuit-ui';

export default function App() {
  return <ToastProvider>{/* Your content goes here... */}</ToastProvider>;
}
```

--------------------------------

### Implement NotificationBanner with images

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/NotificationBanner/NotificationBanner.mdx

Demonstrates how to use the image prop with either a built-in illustration or a source URL.

```tsx
import { NotificationBanner, type NotificationBannerProps } from '@sumup-oss/circuit-ui';

// with a circuit-ui illustration
function Banner(props: NotificationBannerProps) {
  return (
    <NotificationBanner {...props} image={{ illustration: 'celebration', size: 180 } } />
  )
}

// with a source URL
function Banner(props: NotificationBannerProps) {
  return (
    <NotificationBanner {...props} image={{ src: 'https://example.com/image.png', alt: "" }} />
  )
}
```

--------------------------------

### Incorrect usage of Emotion.js theme

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/prefer-custom-properties/README.md

Examples of code that will be flagged by the rule for using the theme object directly.

```tsx
const styles = (theme) => css`
  padding: ${theme.spacings.kilo};
`;

const Box = styled.div`
  padding: ${(theme) => theme.spacings.kilo};
`;

function Component() {
  const theme = useTheme();
  return <div style={{ padding: theme.spacings.kilo }} />;
}
```

--------------------------------

### Run linting and formatting

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/contributing/3-testing.mdx

Commands to check for linting issues or automatically apply fixes.

```bash
npm run lint
# Automatically fix (some) issues
npm run lint:fix
```

--------------------------------

### Incorrect usage of custom properties

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-invalid-custom-properties/README.md

Example of an invalid CSS custom property usage that will trigger the rule.

```css
color: var(--cui-invalid-property);
```

--------------------------------

### Sort the icons manifest file

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/icons/CONTRIBUTING.md

Use jq to sort the icons manifest file by category, name, and size.

```bash
jq '.icons|=sort_by(.category,.name,-(.size|tonumber))' packages/icons/manifest.json > tmp.json && mv tmp.json packages/icons/manifest.json
```

--------------------------------

### Apply standard naming conventions for components and props

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/contributing/2-code-conventions.mdx

Use standard component names and concise prop names, ensuring event handlers follow the 'onVerb' or 'onVerbNoun' pattern.

```tsx
// Do: Use standard component names and short prop names
<DatePicker onClick={fn} nextButton="Next" prevButton="Previous" />

// Don't: Come up with unusual component names or name handlers without the `on` prefix
<CalendarTag selectDate={fn} />
```

--------------------------------

### Incorrect usage of deprecated props

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-deprecated-props/README.md

This example shows a component using a deprecated prop that will be flagged by the rule.

```tsx
function Component() {
  return <Body variant="alert" />;
}
```

--------------------------------

### Configure rules

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/stylelint-plugin-circuit-ui/README.md

Enable specific rules under the rules section of your configuration.

```json
{
  "rules": {
    "circuit-ui/<rule-name>": true
  }
}
```

--------------------------------

### Configure custom image width

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/NotificationBanner/NotificationBanner.mdx

Shows how to set a custom width for an image source.

```tsx
import { NotificationBanner, type NotificationBannerProps } from '@sumup-oss/circuit-ui';

function Banner(props: NotificationBannerProps) {
  return (
    <NotificationBanner {...props} image={{ src: 'https://example.com/image.png', alt: "", width: '120' }} />
  )
}
```

--------------------------------

### Extend Jest matchers for aria-disabled

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Custom Jest setup to support the new aria-disabled attribute in tests.

```js
// jest.setup.js
import { toBeDisabled, toBeEnabled } from "@testing-library/jest-dom/matchers";

function isAriaDisabled(element) {
  return (
    element.hasAttribute("aria-disabled") &&
    element.getAttribute("aria-disabled") === "true"
  );
}

expect.extend({
  toBeDisabled(element) {
    const isDisabled =
      toBeDisabled.bind(this)(element).pass || isAriaDisabled(element);
    return {
      pass: isDisabled,
      message: () => {
        const is = isDisabled ? "is" : "is not";
        return [
          this.utils.matcherHint(
            `${this.isNot ? ".not" : ""}.toBeDisabled`,
            "element",
            ""
          ),
          "",
          `Received element ${is} disabled:`,
          `  ${this.utils.printReceived(element.cloneNode(false))}`,
        ].join("\n");
      },
    };
  },
  toBeEnabled(element) {
    const isEnabled =
      toBeEnabled.bind(this)(element).pass || !isAriaDisabled(element);

    return {
      pass: isEnabled,
      message: () => {
        const is = isEnabled ? "is" : "is not";
        return [
          this.utils.matcherHint(
            `${this.isNot ? ".not" : ""}.toBeEnabled`,
            "element",
            ""
          ),
          "",
          `Received element ${is} enabled:`,
          `  ${this.utils.printReceived(element.cloneNode(false))}`,
        ].join("\n");
      },
    };
  },
});
```

--------------------------------

### Run unit tests

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/contributing/3-testing.mdx

Executes the unit test suite in watch mode.

```bash
npm run test
```

--------------------------------

### Configure custom styled utility

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Legacy approach for typing the theme using CreateStyled.

```ts
// utils/styled.ts
import styled, { CreateStyled } from "@emotion/styled";
import { Theme } from "@sumup/design-tokens";

export default styled as CreateStyled<Theme>;
```

--------------------------------

### Incorrect usage of deprecated icons

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-deprecated-icons/README.md

Example of code that triggers the no-deprecated-icons rule due to the use of an obsolete icon.

```tsx
import { Add } from '@sumup-oss/icons'
function Component() {
  return <Add />;
}
```

--------------------------------

### Currency Selection

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/CurrencyInput/CurrencyInput.mdx

Demonstrates how to use the currency prop to define the input's currency type.

```jsx
<Story of={Stories.Currencies} />
```

--------------------------------

### Incorrect usage of renamed props

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-renamed-props/README.md

Examples of code that trigger the no-renamed-props rule due to the use of deprecated prop names or values.

```tsx
// Since Circuit UI v9
function Component() {
  return (
    <div>
      <Display size="one" />
      <Headline size="three" />
      <Body size="two" />
    </div>
  );
}

// Since Circuit UI v7.5
function Component() {
  return (
    <div>
      <Avatar size="giga" />
      <Hamburger size="kilo" />
      <ProgressBar size="byte" />
      <SelectorGroup size="kilo" />
      <Spinner size="byte" />
      <Button size="kilo" />
      <IconButton size="kilo" label="Add to card">
        <Add />
      </IconButton>
    </div>
  );
}

// Badge → Status
function Component() {
  return (
    <Badge variant="danger" circle>
      1
    </Badge>
  );
}
```

--------------------------------

### Configure the ESLint plugin

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/README.md

Add the plugin to your ESLint configuration file.

```json
{
  "plugins": ["@sumup-oss/circuit-ui"]
}
```

--------------------------------

### Migrate color tokens

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Replace legacy theme color references with semantic CSS variables.

```diff
-color: ${theme.colors.p500};
+color: var(--cui-fg-accent);
```

--------------------------------

### Incorrect usage of default props

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-default-props/README.md

Examples of code that will be flagged by the rule because the props provided match the component's default values.

```jsx
import { Body, Button, IconButton } from '@sumup-oss/circuit-ui';

<Body size="m" color="normal">Hello</Body>;
<Button size="m" variant="secondary">Submit</Button>;
<IconButton size="m" variant="secondary" icon={More}>
  More
</IconButton>;
```

--------------------------------

### ActionMenu with offset

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/ActionMenu/ActionMenu.mdx

Demonstrates how to position the ActionMenu with an offset.

```jsx
<Story of={Stories.Offset} />
```

--------------------------------

### Implement a list of UI components

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/List/List.mdx

Use a standard unordered list with role="list" and list-style: none to render complex UI elements like cards while maintaining accessibility.

```jsx
function ArticleList(articles) {
  return (
    <ul
      css={css`
        list-style: none;
      `}
      role="list"
    >
      {articles.map((article, i) => (
        <li key={i}>
          <ArticleCard article={article} />
        </li>
      ))}
    </ul>
  );
}
```

--------------------------------

### Correct component imports

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/component-lifecycle-imports/README.md

Shows the corrected import paths for components that have moved to the stable entrypoint.

```tsx
import { Timestamp } from '@sumup-oss/circuit-ui';
import type { TimestampProps } from '@sumup-oss/circuit-ui';
```

--------------------------------

### Incorrect usage of deprecated custom properties

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/no-deprecated-custom-properties/README.md

This example shows CSS code that triggers the rule due to the use of outdated typography custom properties.

```css
.class {
  font-size: var(--cui-typography-headline-one-font-size);
  line-height: var(--cui-typography-headline-one-line-height);
}
```

--------------------------------

### Correct usage of CSS custom properties

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/prefer-custom-properties/README.md

Examples of code using CSS custom properties, which are not flagged by the rule. Note that media queries are excluded from this rule.

```tsx
const styles = () => css`
  padding: var(--cui-spacings-kilo);
`;

const Box = styled.div`
  padding: var(--cui-spacings-kilo);
`;

function Component() {
  return <div style={{ padding: 'var(--cui-spacings-kilo)' }} />;
}

// CSS custom properties aren't supported inside media queries,
// so the rule doesn't flag or replace `theme.mq.*` tokens.
const mediaQueries = (theme) => css`
  ${theme.mq.kilo} {
    display: flex;
  }
`;
```

--------------------------------

### Implement tab-like navigation

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/Tabs/Tabs.mdx

Configure TabList and Tab components to render as navigation elements instead of standard tab semantics.

```tsx
<TabList as="navigation">
  <Tab as="listitem" href="/home">Home</Tab>
  <Tab as="listitem" href="/about">About</Tab>
  <Tab as="listitem" href="/contact">Contact</Tab>
</TabList>
```

--------------------------------

### useFocusList()

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/hooks/useFocusList/useFocusList.mdx

The useFocusList hook returns props that should be spread onto the container element of your list to enable keyboard navigation.

```APIDOC
## useFocusList()

### Description
Enables keyboard navigation for a list of focusable elements using arrow keys.

### Signature
```ts
function useFocusList(): {
  'data-focus-list': string;
  'onKeyDown': (event: KeyboardEvent) => void;
};
```

### Returns
- **data-focus-list** (string) - An attribute used to identify the list container.
- **onKeyDown** (function) - A keyboard event handler to be attached to the list container to manage focus navigation.
```

--------------------------------

### useMedia(query: string, initialState = false): boolean

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/hooks/useMedia/useMedia.mdx

Tracks the state of a media query and returns a boolean indicating if the query matches.

```APIDOC
## useMedia(query, initialState)

### Description
Tracks the state of a CSS media query. Returns true if the media query matches, otherwise false.

### Signature
`function useMedia(query: string, initialState?: boolean): boolean`

### Parameters
- **query** (string) - Required - The CSS media query string to track.
- **initialState** (boolean) - Optional - The default value to return during server-side rendering or before the media query is evaluated. Defaults to `false`.

### Returns
- **boolean** - Returns `true` if the media query matches the current environment, otherwise `false`.
```

--------------------------------

### Importing Experimental Components

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/introduction/3-component-lifecycle.mdx

Experimental components are imported from the experimental sub-package.

```tsx
import { Component } from '@sumup-oss/circuit-ui/experimental';
```

--------------------------------

### Import styles

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/illustrations/README.md

Include the package styles in your application.

```tsx
import '@sumup-oss/illustration/styles.css';
```

--------------------------------

### Apply media queries using the theme

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/features/1-theme.mdx

Use the theme's media query helpers within Emotion CSS blocks.

```ts
import { css } from '@emotion/react';

const styles = ({ theme }) => css`
  ${theme.mq.mega} {
    padding-top: ${theme.spacings.peta};
  }
`;
```

--------------------------------

### Tooltip implementation

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/Tooltip/Tooltip.mdx

Displays the base Tooltip component and its associated properties.

```jsx
<Story of={Stories.Base} />
<Props of={Stories.Base} />
```

--------------------------------

### Apply Style Mixins

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/styles/style-mixins.mdx

Demonstrates using style mixins directly with the css prop or within styled components.

```tsx
import { clearfix, spacing } from '@sumup-oss/circuit-ui/legacy';
import styled from '@emotion/styled';
import { css } from '@emotion/react';

// Pass the style mixin directly to the `css` prop
const Basic = () => <div css={clearfix} />;

// Some style mixins accept options
const Options = () => <div css={spacing('mega')} />;

// Style mixins can also be used in a style function...
const someStyles = ({ theme }) => css`
  &:focus {
    ${focusOutline()};
  }
`;

// ...or passed to a styled component directly
const StyledComponent = styled.div(someStyles, clearfix);
```

--------------------------------

### Project directory structure

Source: https://github.com/sumup-oss/circuit-ui/blob/main/templates/astro/README.md

Visual representation of the standard file layout for the Astro project.

```text
/
├── public/
├── src/
│   └── pages/
│       └── index.astro
└── package.json
```

--------------------------------

### Import styles and theme

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/introduction/2-getting-started.mdx

Import fonts and design tokens before the component styles to ensure the theme is correctly applied.

```tsx
// /app/layout.tsx or /pages/_app.tsx for Next.js
import '@sumup-oss/design-tokens/fonts.css';
import '@sumup-oss/design-tokens/light.css';
import '@sumup-oss/circuit-ui/styles.css';
```

--------------------------------

### Render Table with Component Rows

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/Table/Table.mdx

Demonstrates how to pass objects instead of strings as children to table headers and rows.

```jsx
<Story of={Stories.WithComponentRows} />
```

--------------------------------

### NotificationInline with headline and action

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/NotificationInline/NotificationInline.mdx

Demonstrates adding an optional headline and action button to the notification.

```jsx
<Story of={Stories.WithHeadlineAndAction} />
```

--------------------------------

### Timestamp Format Styles

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/Timestamp/Timestamp.mdx

Demonstrates the use of formatStyles and includeTime props to control verbosity and time display.

```jsx
<Story of={Stories.FormatStyles} />
```

--------------------------------

### Run development with accessibility errors disabled

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Temporarily bypass runtime accessibility errors in development by setting the environment variable.

```sh
UNSAFE_DISABLE_ACCESSIBILITY_ERRORS=true yarn dev # or yarn start
```

--------------------------------

### Access legacy breakpoint and media query theme properties

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/features/1-theme.mdx

Access breakpoint and media query definitions within the legacy JS theme.

```text
theme.mq.[untilKilo|kilo|kiloToMega|mega|untilMega|megaToGiga|giga|gigaToTera|tera]
theme.breakpoints.[untilKilo|kilo|kiloToMega|mega|untilMega|megaToGiga|giga|gigaToTera|tera]
```

--------------------------------

### Importing Legacy Components

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/introduction/3-component-lifecycle.mdx

Legacy components are imported from the legacy sub-package.

```tsx
import { Component } from '@sumup-oss/circuit-ui/legacy';
```

--------------------------------

### Configure ESLint rules

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/eslint-plugin-circuit-ui/README.md

Enable specific rules under the rules section of your configuration.

```json
{
  "rules": {
    "@sumup-oss/circuit-ui/<rule-name>": "error"
  }
}
```

--------------------------------

### Import Icon as React Component

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/icons/README.md

Basic usage of an icon imported as a React component.

```tsx
import { Check } from '@sumup-oss/icons';

const SuccessMessage = ({ description }) => (
  <div>
    <Check />
    <span>{description}</span>
  </div>
);
```

--------------------------------

### Upgrade Circuit UI dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Command to update the library and its peer dependencies to the latest version.

```sh
npm upgrade @sumup-oss/circuit-ui @sumup-oss/design-tokens @sumup-oss/icons @sumup-oss/stylelint-plugin-circuit-ui @sumup-oss/eslint-plugin-circuit-ui
```

--------------------------------

### Upgrade Circuit UI dependencies

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Command to update the core library and its required peer dependencies to the latest versions.

```sh
npm upgrade @sumup-oss/circuit-ui @sumup-oss/design-tokens @sumup-oss/icons
```

--------------------------------

### Configure ModalProvider

Source: https://github.com/sumup-oss/circuit-ui/blob/main/skills/circuit-ui/references/components/NotificationModal.mdx

Wrap your application in the ModalProvider to enable the useNotificationModal hook.

```tsx
import { ModalProvider } from "@sumup-oss/circuit-ui";

export default function App() {
  return <ModalProvider>{/* Your content here... */}</ModalProvider>;
}
```

--------------------------------

### Construct URL manually

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/illustrations/README.md

Directly reference the CDN URL for CSS background images.

```css
.illustration {
  background-image: url('https://circuit.sumup.com/illustrations/bookings_dark.svg');
}
```

--------------------------------

### Load Icon from CDN URL

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/icons/README.md

Use the getIconURL helper or manual URL construction to load icons from the CDN.

```tsx
import { getIconURL } from '@sumup-oss/icons';

const SuccessMessage = ({ message }) => (
  <div>
    <img src={getIconURL('check', '24')} alt="" />
    <span>{message}</span>
  </div>
);
```

```css
.icon {
  background-image: url('https://circuit.sumup.com/icons/v2/check_24.svg');
}
```

--------------------------------

### Migrate design tokens to CSS custom properties

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Replace JavaScript theme object properties with CSS custom properties.

```diff
-${theme.borderRadius.circle}
+var(--cui-border-radius.circle)
```

--------------------------------

### Configure Babel for new JSX transform

Source: https://github.com/sumup-oss/circuit-ui/blob/main/MIGRATION.md

Recommended Babel configuration for Next.js and Emotion 10 compatibility.

```json
{
  "presets": [
    [
      "next/babel",
      {
        "preset-react": {
          "runtime": "automatic",
          "importSource": "@emotion/core"
        }
      }
    ]
  ],
  "plugins": [["babel-plugin-emotion", { "cssPropOptimization": true }]]
}
```

--------------------------------

### Load illustration from a URL

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/illustrations/README.md

Use the getIllustrationURL helper for type-safe access to hosted SVG files.

```tsx
import { getIllustrationURL } from '@sumup-oss/illustrations';

const SuccessScreen = ({ message }) => (
  <div>
    <img src={getIllustrationURL('error-1', 'light')} alt=""/>
    <span>Payment failed. Please contact your card provider.</span>
  </div>
);
```

--------------------------------

### Render a Tag with prefix or suffix

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/Tag/Tag.mdx

Displays the Tag component with additional content as a prefix or suffix.

```jsx
<Story of={Stories.Affix} />
```

--------------------------------

### Render ImageInput with custom components

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/ImageInput/ImageInput.mdx

Demonstrates using custom img or div elements as the visual component for the ImageInput.

```jsx
<Story of={Stories.CustomComponentImg} />
```

```jsx
<Story of={Stories.CustomComponentDiv} />
```

--------------------------------

### Preload font files

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/design-tokens/README.md

Add preload links to the document head to optimize font loading performance.

```html
<link
  rel="preload"
  href="https://static.sumup.com/fonts/sumup/sumup-narrow-latin-s.woff2"
  as="font"
  type="font/woff2"
  crossorigin
/>
<link
  rel="preload"
  href="https://static.sumup.com/fonts/sumup/sumup-black-latin-s.woff2"
  as="font"
  type="font/woff2"
  crossorigin
/>
```

--------------------------------

### AutocompleteInput with AllowNewItems

Source: https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/components/AutocompleteInput/AutocompleteInput.mdx

Enables the selection of user-provided input as a valid option.

```jsx
<Story of={Stories.AllowNewItems} />
```

--------------------------------

### Override base components with ComponentsContext

Source: https://github.com/sumup-oss/circuit-ui/blob/main/docs/features/3-components.mdx

Use the ComponentsContext.Provider to inject custom implementations for base components like Link. Circuit UI merges these with defaults, allowing partial overrides.

```javascript
import { Link } from 'react-router-dom';
import { ComponentsContext, Button } from '@sumup-oss/circuit-ui';

const CustomLink = ({ to, ...props }) => <Link href={to} {...props} />;

const App = () => (
  <ComponentsContext.Provider value={{ Link: CustomLink }}>
    <Button href="/">Home</Button>
  </ComponentsContext.Provider>
);

export default App;
```
Tokens:
Raw