Backstage UI

https://ui.backstage.io
Admin
Backstage UI is an open-source design system built with React, TypeScript, and CSS, specifically...
Tokens:70,175
Snippets:885
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Theming Migration Guide for Background

Source: https://ui.backstage.io/components/box

Provides a migration example for updating Box background props from explicit neutral levels to the new 'neutral' value.

```javascript
// Before
<Box bg="neutral-2">...</Box>

// After
<Box bg="neutral">
  <Box bg="neutral">...</Box>
</Box>
```

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

### Install Backstage UI Package

Source: https://ui.backstage.io/get-started/installation

Install the @backstage/ui package using Yarn. This command should be run in your 'packages/app' directory.

```bash
yarn add @backstage/ui
```

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

### Basic Combobox Usage

Source: https://ui.backstage.io/components/combobox

Demonstrates the basic setup of a Combobox with a label and a list of options.

```javascript
import { Combobox } from '@backstage/ui';

<Combobox
    name="font"
    label="Font Family"
    options={[
      { value: 'sans', label: 'Sans-serif' },
      { value: 'serif', label: 'Serif' },
      { value: 'mono', label: 'Monospace' },
      { value: 'cursive', label: 'Cursive' },
    ]}
/>
```

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

### Manual BUIProvider Setup

Source: https://ui.backstage.io/get-started/installation

Manually set up the BUIProvider within a React Router context if not using the automatic setup. Pass the useAnalytics hook.

```typescript
import { BUIProvider } from '@backstage/ui';
import { useAnalytics } from '@backstage/core-plugin-api';
import { BrowserRouter } from 'react-router-dom';

// BUIProvider must be inside a Router for client-side navigation
<BrowserRouter>
  <BUIProvider useAnalytics={useAnalytics}>
    <AppContent />
  </BUIProvider>
</BrowserRouter>
```

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

### Interactive Card Example (onPress)

Source: https://ui.backstage.io/components/card

Example demonstrating how to make a card interactive using the onPress prop and a label for accessibility.

```APIDOC
## Card with onPress

### Description
This example shows a card that triggers a function when pressed, with an accessible label for screen readers.

### Method
N/A (Component Usage)

### Parameters
- **onPress** (() => void) - Required - Handler called when the card is pressed.
- **label** (string) - Required - Accessible label for the interactive overlay.

### Request Example
```jsx
<Card
  style={{ width: '300px' }}
  onPress={() => console.log('Card pressed')}
  label="View component details"
>
  <CardHeader>Interactive Card</CardHeader>
  <CardBody>Click anywhere on this card to trigger the press handler.</CardBody>
  <CardFooter>Click to interact</CardFooter>
</Card>
```
```

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

### Interactive Card Example (href)

Source: https://ui.backstage.io/components/card

Example demonstrating how to make a card navigate to a URL using the href prop and a label for accessibility.

```APIDOC
## Card with href

### Description
This example shows a card that navigates to a specified URL when clicked, with an accessible label for screen readers.

### Method
N/A (Component Usage)

### Parameters
- **href** (string) - Required - URL to navigate to.
- **label** (string) - Required - Accessible label for the interactive overlay.

### Request Example
```jsx
<Card
  style={{ width: '300px' }}
  href="https://backstage.io"
  label="Open Backstage documentation"
>
  <CardHeader>Link Card</CardHeader>
  <CardBody>This card navigates to a URL when clicked.</CardBody>
  <CardFooter>Opens backstage.io</CardFooter>
</Card>
```
```

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

### Link Usage Example

Source: https://ui.backstage.io/components/link

Basic import and usage of the Link component for navigation. Ensure you import Link from '@backstage/ui'.

```javascript
import { Link } from '@backstage/ui';

<Link href="/">Sign up for Backstage</Link>
```

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

### Avatar Migration Guide

Source: https://ui.backstage.io/components/avatar

Provides code examples for migrating from older versions of the Avatar component, focusing on prop changes and size updates.

```javascript
# Remove Base UI-specific props
- <Avatar src="..." name="..." render={...} />
+ <Avatar src="..." name="..." />
```

```javascript
# Update large size usage to x-large for same visual size
- <Avatar src="..." name="..." size="large" />
+ <Avatar src="..." name="..." size="x-large" />
```

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

### List Usage Example

Source: https://ui.backstage.io/components/list

Basic import and usage of the List and ListRow components. Ensure you have the necessary items prop defined.

```jsx
import { List, ListRow } from '@backstage/ui';

<List aria-label="Programming languages" items={items}>
  {item => <ListRow id={item.id}>{item.label}</ListRow>}
</List>
```

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

### Basic Menu Usage

Source: https://ui.backstage.io/components/menu

Demonstrates the basic setup for a menu with a trigger and menu items. Ensure to import MenuTrigger, Menu, and MenuItem from '@backstage/ui'.

```javascript
import { MenuTrigger, Menu, MenuItem } from '@backstage/ui';

<MenuTrigger>
  <Button>Menu</Button>
  <Menu>
    <MenuItem>Item 1</MenuItem>
    <MenuItem>Item 2</MenuItem>
  </Menu>
</MenuTrigger>
```

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

### Menu with Icons

Source: https://ui.backstage.io/components/menu

Shows how to add start icons to menu items using the `iconStart` prop. This enhances visual clarity and user experience.

```jsx
<MenuTrigger>
  <Button variant="secondary">Menu</Button>
  <Menu>
    <MenuItem iconStart={<RiFileLine />}>New File</MenuItem>
    <MenuItem iconStart={<RiFolderLine />}>New Folder</MenuItem>
    <MenuItem iconStart={<RiImageLine />}>New Image</MenuItem>
  </Menu>
</MenuTrigger>
```

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

### Checkbox Usage Example

Source: https://ui.backstage.io/components/checkbox

Demonstrates basic usage of the Checkbox component with a label. Import Checkbox from '@backstage/ui'.

```javascript
import { Checkbox } from '@backstage/ui';

<Checkbox>Accept terms</Checkbox>
```

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

### Popover Placement Example

Source: https://ui.backstage.io/components/popover

Illustrates different placement options for the Popover component relative to its trigger element.

```html
TopRightBottomLeft
```

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

### Button Usage

Source: https://ui.backstage.io/components/button

Import and use the Button component with basic content. Ensure you have the '@backstage/ui' package installed.

```jsx
import { Button } from '@backstage/ui';

<Button>Click me</Button>
```

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

### Alert Usage Example

Source: https://ui.backstage.io/components/alert

Basic import and usage of the Alert component with an informational status and title.

```jsx
import { Alert } from '@backstage/ui';

<Alert status="info" title="This is an informational message" />
```

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

### Theming Migration Guide for Box Component

Source: https://ui.backstage.io/components/flex

Provides a migration guide for the Box component's background prop, changing from explicit neutral levels to a single 'neutral' value that auto-increments. This ensures consistent theming across nested components.

```javascript
// Before
<Box bg="neutral-2">...</Box>

// After
<Box bg="neutral">
  <Box bg="neutral">
    ...
  </Box>
</Box>
```

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

### Tooltip Usage Example

Source: https://ui.backstage.io/components/tooltip

Demonstrates how to use the Tooltip component with a trigger and button. Ensure you import TooltipTrigger, Tooltip, and Button from '@backstage/ui'.

```javascript
import { TooltipTrigger, Tooltip, Button } from '@backstage/ui';

<TooltipTrigger>
  <Button>Hover me</Button>
  <Tooltip>Helpful information</Tooltip>
</TooltipTrigger>
```

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

### RadioGroup Basic Usage

Source: https://ui.backstage.io/components/radio-group

Demonstrates the basic setup for a RadioGroup with two options. Import RadioGroup and Radio from '@backstage/ui'.

```jsx
import { RadioGroup, Radio } from '@backstage/ui';

<RadioGroup label="Select an option">
  <Radio value="option1">Option 1</Radio>
  <Radio value="option2">Option 2</Radio>
</RadioGroup>
```

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

### Import and Use VisuallyHidden Component

Source: https://ui.backstage.io/components/visually-hidden

Demonstrates how to import and use the VisuallyHidden component to hide content. This is the basic setup for utilizing the component.

```javascript
import { VisuallyHidden } from '@backstage/ui';

<VisuallyHidden>
  This content is visually hidden but accessible to screen readers
</VisuallyHidden>
```

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

### External Link Example

Source: https://ui.backstage.io/components/link

Demonstrates how to use the `target="_blank"` prop to open links in a new tab. This is useful for external URLs.

```javascript
<Link href="#" target="_blank">
  Sign up for Backstage
</Link>
```

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

### Disabled Switch Example

Source: https://ui.backstage.io/components/switch

Shows how to render a disabled Switch component. This prevents user interaction.

```javascript
<Switch isDisabled />
```

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

### Popover Usage Example

Source: https://ui.backstage.io/components/popover

Demonstrates the basic usage of the Popover component by wrapping a trigger button and its content with DialogTrigger.

```javascript
import { DialogTrigger, Popover, Button, Text } from '@backstage/ui';

<DialogTrigger>
  <Button>Open Popover</Button>
  <Popover>
    <Text>Popover content</Text>
  </Popover>
</DialogTrigger>
```

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

### ButtonLink Usage Example

Source: https://ui.backstage.io/components/button-link

Import and use the ButtonLink component with a specified href. Ensure you have the ButtonLink component imported from '@backstage/ui'.

```javascript
import { ButtonLink } from '@backstage/ui';

<ButtonLink href="https://ui.backstage.io">Button</ButtonLink>
```

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

### Avatar Usage Example

Source: https://ui.backstage.io/components/avatar

Basic usage of the Avatar component with an image source and a name for fallback.

```javascript
import { Avatar } from '@backstage/ui';

<Avatar src="https://example.com/user.jpg" name="Jane Doe" />
```

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

### Container Usage Example

Source: https://ui.backstage.io/components/container

Import and use the Container component to wrap your plugin's main content. This component centers content and constrains its maximum width.

```javascript
import { Container } from "@backstage/ui";

<Container>
  {/* Your plugin's main content */}
</Container>
```

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

### Menu with Autocomplete Input

Source: https://ui.backstage.io/components/menu

Provides an example of a menu with an integrated autocomplete search input using `MenuAutocomplete`. The placeholder text can be customized.

```jsx
<MenuTrigger>
  <Button variant="secondary">Search</Button>
  <MenuAutocomplete placeholder="Type to search...">
    <MenuItem>Option 1</MenuItem>
    <MenuItem>Option 2</MenuItem>
    <MenuItem>Option 3</MenuItem>
  </MenuAutocomplete>
</MenuTrigger>
```

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

### Basic ToggleButtonGroup Usage

Source: https://ui.backstage.io/components/toggle-button-group

Demonstrates the basic setup of a ToggleButtonGroup with single selection mode. Import ToggleButtonGroup and ToggleButton from '@backstage/ui'.

```jsx
import { ToggleButtonGroup, ToggleButton } from '@backstage/ui';

<ToggleButtonGroup selectionMode="single">
  <ToggleButton id="dogs">Dogs</ToggleButton>
  <ToggleButton id="cats">Cats</ToggleButton>
  <ToggleButton id="birds">Birds</ToggleButton>
</ToggleButtonGroup>
```

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

### Flex Direction Example

Source: https://ui.backstage.io/components/flex

Demonstrates how to set the direction of the flex container to 'column' and apply a gap. This is useful for vertical layouts.

```javascript
<Flex direction="column" gap="2">
  <DecorativeBox>First</DecorativeBox>
  <DecorativeBox>Second</DecorativeBox>
  <DecorativeBox>Third</DecorativeBox>
</Flex>
```

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

### List with Descriptions

Source: https://ui.backstage.io/components/list

Example of rendering a List where each row includes a description. The description is passed via the 'description' prop on ListRow.

```jsx
<List aria-label="Programming languages" items={items}>
  {item => (
    <ListRow id={item.id} icon={item.icon} description={item.description}>
      {item.label}
    </ListRow>
  )}
</List>
```

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

### List with Icons

Source: https://ui.backstage.io/components/list

Example of rendering a List where each row includes an icon. The icon is passed via the 'icon' prop on ListRow.

```jsx
<List aria-label="Programming languages" items={items}>
  {item => (
    <ListRow id={item.id} icon={item.icon}>
      {item.label}
    </ListRow>
  )}
</List>
```

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

### Table with Search, Sorting, Pagination, and Row Selection

Source: https://ui.backstage.io/components/table

This example demonstrates a table with multiple features enabled, including search, sorting, pagination, and row selection. It's suitable for complex data display scenarios.

```javascript
import { Table } from '@backstage/ui-components';
import { useTable } from '@backstage/plugin-catalog-react';

// Example usage within a React component
const MyTable = () => {
  const { tableProps, search, filter, pagination } = useTable({
    // ... useTable options like mode, getData, etc.
  });

  return (
    <>
      {/* Search, Filter, and Pagination controls would go here */}
      <Table {...tableProps} />
    </>
  );
};

```

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

### Migrate to New Table Hook API (v0.11.0)

Source: https://ui.backstage.io/components/table

This example shows the migration steps from the old Table API to the new `useTable` hook API, including updated imports and rendering logic.

```javascript
-import { Table, useTable } from '@backstage/ui';
-const { data, paginationProps } = useTable({ data: items, pagination: {...} });
+import { Table, useTable, type ColumnConfig } from '@backstage/ui';
+const { tableProps } = useTable({
+  mode: 'complete',
+  getData: () => items,
+});
```

```javascript
-<Table aria-label="My table">
-  <TableHeader>...</TableHeader>
-  <TableBody items={data}>...</TableBody>
-</Table>
-<TablePagination {...paginationProps} />
+
+const columns: ColumnConfig<Item>[] = [
+  { id: 'name', label: 'Name', isRowHeader: true, cell: item => <CellText title={item.name} /> },
+  { id: 'type', label: 'Type', cell: item => <CellText title={item.type} /> },
+];
+
+<Table columnConfig={columns} {...tableProps} />
```

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

### TagGroup with Links

Source: https://ui.backstage.io/components/tag-group

Example of creating a TagGroup where each tag links to a specific URL. This is useful for navigation based on tag categories.

```jsx
<TagGroup>
  <Tag href="/items/banana">Banana</Tag>
  <Tag href="/items/apple">Apple</Tag>
  <Tag href="/items/orange">Orange</Tag>
</TagGroup>
```

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

### Simple PluginHeader Example

Source: https://ui.backstage.io/components/plugin-header

A simple PluginHeader with a title, a link for the title, and custom action buttons in the toolbar. Use this when you need to add interactive elements or link the title to a specific page.

```javascript
<PluginHeader
  title="My plugin"
  titleLink="/"
  customActions={
    <>
      <ButtonIcon variant="tertiary" icon={<RiCloudy2Line />} />
      <ButtonIcon variant="tertiary" icon={<RiEmotionHappyLine />} />
      <ButtonIcon variant="tertiary" icon={<RiHeartLine />} />
    </>
  }
/>
```

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

### Basic CheckboxGroup Usage

Source: https://ui.backstage.io/components/checkbox-group

Demonstrates the basic setup for a CheckboxGroup with a label and default selected values. Ensure to import CheckboxGroup and Checkbox from '@backstage/ui'.

```jsx
import { CheckboxGroup, Checkbox } from '@backstage/ui';

<CheckboxGroup label="Choose platforms for notifications" defaultValue={['github']}>
  <Checkbox value="github">GitHub</Checkbox>
  <Checkbox value="slack">Slack</Checkbox>
  <Checkbox value="email">Email</Checkbox>
</CheckboxGroup>
```

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

### Standalone Link Example

Source: https://ui.backstage.io/components/link

Illustrates the `standalone` prop, which removes the default underline. The underline appears on hover, providing a cleaner look.

```javascript
<Flex gap="4">
  <Link href="#">Default link</Link>
  <Link href="#" standalone>Standalone link</Link>
</Flex>
```

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

### Alert with Description

Source: https://ui.backstage.io/components/alert

Shows how to use the 'description' prop to add more detailed information to an alert. Examples include success, warning, and danger statuses with descriptions.

```jsx
<Flex direction="column" gap="4">
  <Alert
    status="info"
    icon={true}
    title="New Feature Available"
    description="We've added support for custom table columns. Check the documentation to learn more."
  />
  <Alert
    status="success"
    icon={true}
    title="Deployment Successful"
    description="Your application has been deployed to production. All health checks passed."
  />
  <Alert
    status="warning"
    icon={true}
    title="Pending Review"
    description="Please review the following items before proceeding with the deployment."
  />
  <Alert
    status="danger"
    icon={true}
    title="Authentication Failed"
    description="Unable to verify your credentials. Please check your username and password and try again."
  />
</Flex>
```

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

### Flex Component Usage

Source: https://ui.backstage.io/components/flex

Import and use the Flex component to create a layout with a specified gap. This is the basic setup for using the Flex component.

```javascript
import { Flex } from '@backstage/ui';

<Flex gap="4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Flex>
```

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

### Avatar Fallback Example

Source: https://ui.backstage.io/components/avatar

Shows the avatar component using initials fallback when the provided image URL is invalid or unavailable.

```javascript
<Avatar
  src="https://avatars.githubusercontent.com/u/15406AAAAAAAAA"
  name="Charles de Dreuille"
/>
```

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

### Menu with Listbox and Autocomplete

Source: https://ui.backstage.io/components/menu

Demonstrates using `MenuAutocompleteListbox` for a selectable list with filtering capabilities. The placeholder guides the user on how to interact.

```jsx
<MenuTrigger>
  <Button variant="secondary">Select</Button>
  <MenuAutocompleteListbox placeholder="Type to filter...">
    <MenuListBoxItem>Option 1</MenuListBoxItem>
    <MenuListBoxItem>Option 2</MenuListBoxItem>
    <MenuListBoxItem>Option 3</MenuListBoxItem>
  </MenuAutocompleteListbox>
</MenuTrigger>
```

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

### SearchAutocomplete with Selection Handling

Source: https://ui.backstage.io/components/search-autocomplete

This example demonstrates how to use SearchAutocomplete to filter a list of fruits and handle item selection using the onAction prop. It resets the input value upon selection.

```javascript
function Example() {
  const [inputValue, setInputValue] = useState('');
  const [selected, setSelected] = useState<string | null>(null);

  const filtered = fruits.filter(fruit =>
    fruit.name.toLowerCase().includes(inputValue.toLowerCase()),
  );

  return (
    <Flex direction="column" gap="4">
      <SearchAutocomplete
        placeholder="Search fruits..."
        inputValue={inputValue}
        onInputChange={setInputValue}
      >
        {filtered.map(fruit => (
          <SearchAutocompleteItem
            key={fruit.id}
            id={fruit.id}
            textValue={fruit.name}
            onAction={() => {
              setSelected(fruit.name);
              setInputValue('');
            }}
          >
            {fruit.name}
          </SearchAutocompleteItem>
        ))}
      </SearchAutocomplete>
      <Text>Last selected: {selected ?? 'none'}</Text>
    </Flex>
  );
}
```

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

### Theming Grid Component

Source: https://ui.backstage.io/components/grid

Example of how to customize the Grid component using CSS classes. The primary class name for the Grid component is 'bui-Grid'.

```css
/* Example CSS for theming */
.bui-Grid {
  /* Custom styles */
}
```

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

### Custom Component with Box and Text

Source: https://ui.backstage.io/

Create custom components by composing existing Backstage UI components. This example shows a simple custom component using Box and Text.

```jsx
<Box bg="neutral">
  <Text>Hello World</Text>
</Box>
```

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

### Grid Basic Usage

Source: https://ui.backstage.io/components/grid

Demonstrates how to set up a basic Grid container with a specified number of columns and gap between items. Import the Grid component from '@backstage/ui'.

```jsx
import { Grid } from '@backstage/ui';

<Grid.Root columns="3" gap="4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Grid.Root>
```

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

### Migrate Checkbox Component (Before)

Source: https://ui.backstage.io/changelog

Example of the previous Checkbox component usage with a label.

```jsx
<Checkbox label="Accept terms" checked={agreed} onChange={setAgreed} />
```

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

### Migrate Checkbox Component (After)

Source: https://ui.backstage.io/changelog

Example of the new Checkbox component usage with children for the label.

```jsx
<Checkbox isSelected={agreed} onChange={setAgreed}>
  Accept terms
</Checkbox>
```

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

### Basic Select Usage

Source: https://ui.backstage.io/components/select

Demonstrates the basic usage of the Select component with a list of options. Import the Select component from '@backstage/ui'.

```jsx
import { Select } from '@backstage/ui';

<Select
    name="font"
    options={[
      { value: 'sans', label: 'Sans-serif' },
      { value: 'serif', label: 'Serif' },
      { value: 'mono', label: 'Monospace' },
      { value: 'cursive', label: 'Cursive' },
    ]}
/>
```

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

### Basic TextField Usage

Source: https://ui.backstage.io/components/text-field

Demonstrates the basic import and usage of the TextField component with a label.

```javascript
import { TextField } from '@backstage/ui';

<TextField label="Email" type="email" />
```

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

### Popover Hidden Arrow Example

Source: https://ui.backstage.io/components/popover

Shows how to hide the arrow that points from the Popover to its trigger element.

```html
Open Popover
```

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

### Import and Basic Usage of Text Component

Source: https://ui.backstage.io/components/text

Demonstrates how to import and use the Text component with default settings. Ensure the Text component is imported from '@backstage/ui'.

```javascript
import { Text } from '@backstage/ui';

<Text>This is a text component</Text>
```

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

### Import and Basic Usage

Source: https://ui.backstage.io/components/date-range-picker

Demonstrates how to import and use the DateRangePicker component with a label.

```javascript
import { DateRangePicker } from '@backstage/ui';

<DateRangePicker label="Date range" />
```

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

### Basic Switch Usage

Source: https://ui.backstage.io/components/switch

Demonstrates the basic import and usage of the Switch component. This is the simplest way to render a switch.

```javascript
import { Switch } from '@backstage/ui';

<Switch />
```

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

### RadioGroup Validation Example

Source: https://ui.backstage.io/components/radio-group

Implements custom validation for the RadioGroup using the 'validate' prop. The 'validationBehavior' is set to 'aria'.

```jsx
<RadioGroup
  label="What is your favorite pokemon?"
  name="pokemon"
  defaultValue="charmander"
  validationBehavior="aria"
  validate={value => (value === 'charmander' ? 'Nice try!' : null)} 
>
  <Radio value="bulbasaur">Bulbasaur</Radio>
  <Radio value="charmander">Charmander</Radio>
  <Radio value="squirtle">Squirtle</Radio>
</RadioGroup>
```

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

### Basic Card Usage

Source: https://ui.backstage.io/components/card

Demonstrates the basic structure of a Card component with header, body, and footer. Import necessary components from '@backstage/ui'.

```javascript
import { Card, CardHeader, CardBody, CardFooter } from '@backstage/ui';

<Card>
  <CardHeader>Header</CardHeader>
  <CardBody>Body</CardBody>
  <CardFooter>Footer</CardFooter>
</Card>
```

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

### Import and Basic Usage of Badge

Source: https://ui.backstage.io/components/badge

Demonstrates how to import and use the basic Badge component. This is suitable for general annotation and categorization.

```javascript
import { Badge } from '@backstage/ui';

<Badge>Badge</Badge>
```

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

### Basic Header Usage

Source: https://ui.backstage.io/components/header

Demonstrates the basic usage of the Header component with a title.

```typescript
import { Header } from '@backstage/ui';

<Header title="Page Title" />
```

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

### Basic Accordion Usage

Source: https://ui.backstage.io/components/accordion

Demonstrates the basic structure of an Accordion with a trigger and panel. Import necessary components from '@backstage/ui'.

```javascript
import { Accordion, AccordionTrigger, AccordionPanel } from '@backstage/ui';

<Accordion>
  <AccordionTrigger title="Toggle Panel" />
  <AccordionPanel>Your content</AccordionPanel>
</Accordion>
```

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

### Use Backstage UI Components

Source: https://ui.backstage.io/get-started/installation

Import and use BUI components like Flex, Button, and Text from '@backstage/ui' in your plugin. Styles are handled globally.

```typescript
import { Flex, Button, Text } from '@backstage/ui';

<Flex>
  <Text>Hello World</Text>
  <Button>Click me</Button>
</Flex>;
```

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

### Basic Box Usage

Source: https://ui.backstage.io/components/box

Demonstrates the basic usage of the Box component with padding and surface background.

```javascript
import { Box } from '@backstage/ui';

<Box p="4" surface="1">
  Content with padding and background
</Box>
```

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

### Collapsible SearchField

Source: https://ui.backstage.io/components/search-field

Demonstrates the 'startCollapsed' prop for space-constrained layouts, where the field expands on focus. Includes examples for both small and medium sizes.

```jsx
<Flex direction="row" gap="4">
  <SearchField aria-label="Search" size="small" startCollapsed />
  <SearchField aria-label="Search" size="medium" startCollapsed />
</Flex>
```

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

### Remove onSurface from Consumer Components

Source: https://ui.backstage.io/components/button-link

Examples showing the removal of the 'onSurface' prop from consumer components, as they now inherit background from the parent container.

```html
<Button onSurface="1" variant="secondary">
<Button variant="secondary">

<ButtonIcon onSurface="2" variant="secondary" />
<ButtonIcon variant="secondary" />

<ToggleButton onSurface="1">
<ToggleButton>

```

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

### PasswordField with Description

Source: https://ui.backstage.io/components/password-field

Illustrates how to add help text below the label using the 'description' prop.

```jsx
<PasswordField
  name="password"
  label="Password"
  description="Enter your password"
/>
```

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

### Menu with Links

Source: https://ui.backstage.io/components/menu

Illustrates using the `href` prop on `MenuItem` to create navigation links, suitable for both internal and external URLs.

```jsx
<MenuTrigger>
  <Button variant="secondary">Menu</Button>
  <Menu>
    <MenuItem href="/home">Home</MenuItem>
    <MenuItem href="/about">About</MenuItem>
    <MenuItem href="/contact">Contact</MenuItem>
  </Menu>
</MenuTrigger>
```

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

### Responsive Grid Columns

Source: https://ui.backstage.io/components/grid

Shows how to configure the number of columns to change at different breakpoints using an object for the 'columns' prop. Supports 'initial' and breakpoint keys like 'md'.

```jsx
<Grid.Root columns={{ initial: '2', md: '4' }} gap="4">
  <DecorativeBox>1</DecorativeBox>
  <DecorativeBox>2</DecorativeBox>
  <DecorativeBox>3</DecorativeBox>
  <DecorativeBox>4</DecorativeBox>
</Grid.Root>
```

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

### Import and Basic Usage of SearchField

Source: https://ui.backstage.io/components/search-field

Demonstrates how to import and use the basic SearchField component in your React application.

```jsx
import { SearchField } from '@backstage/ui';

<SearchField />
```

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

### Basic PasswordField Usage

Source: https://ui.backstage.io/components/password-field

Demonstrates the basic usage of the PasswordField component with a label. Import the component from '@backstage/ui'.

```jsx
import { PasswordField } from '@backstage/ui';

<PasswordField label="Password" />
```

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

### NumberField Basic Usage

Source: https://ui.backstage.io/components/number-field

Demonstrates the basic usage of the NumberField component with label, min/max values, and step.

```javascript
import { NumberField } from '@backstage/ui';

<NumberField label="Minutes" minValue={0} maxValue={59} step={1} />
```

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

### ToggleButtonGroup with Icons and Text

Source: https://ui.backstage.io/components/toggle-button-group

Shows how to use icons alongside text within ToggleButtons, supporting placement at the start or end. Requires importing icons from '@remixicon/react'.

```jsx
import { RiCloudLine, RiStarFill, RiStarLine, RiArrowRightSLine } from '@remixicon/react';

<ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['cloud']}>
  <ToggleButton id="cloud" aria-label="Cloud" iconStart={<RiCloudLine />} />
  <ToggleButton
    id="starred"
    aria-label="Starred"
    iconStart={<RiStarFill />}
  />
  <ToggleButton id="star" iconStart={<RiStarLine />}>
    Star
  </ToggleButton>
  <ToggleButton id="next" iconEnd={<RiArrowRightSLine />}>
    Next
  </ToggleButton>
</ToggleButtonGroup>
```

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

### Dialog with Fixed Width and Scrollable Body

Source: https://ui.backstage.io/components/dialog

Example of a Dialog with a fixed width and a scrollable body for content that exceeds the available height. Use when content might be long.

```jsx
<Dialog width={500} height={300}>
  <DialogHeader>Scrollable Dialog</DialogHeader>
  <DialogBody>
    {/* Long content here that will cause scrolling */}
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
    <p>This is some content.</p>
  </DialogBody>
  <DialogFooter>
    <Button variant="secondary" slot="close">Close</Button>
  </DialogFooter>
</Dialog>
```

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

### Dialog Basic Usage

Source: https://ui.backstage.io/components/dialog

Demonstrates the basic structure of a Dialog component, including its trigger, header, body, and footer. Use this for standard modal dialogs.

```jsx
import {
  Dialog,
  DialogTrigger,
  DialogHeader,
  DialogBody,
  DialogFooter,
} from '@backstage/ui';

<DialogTrigger>
  <Button>Open Dialog</Button>
  <Dialog>
    <DialogHeader>Title</DialogHeader>
    <DialogBody>Content</DialogBody>
    <DialogFooter>
      <Button variant="secondary" slot="close">Close</Button>
    </DialogFooter>
  </Dialog>
</DialogTrigger>
```

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

### Sticky Search Bar Background

Source: https://ui.backstage.io/tokens

Example of using the inherited background color for a sticky element. This ensures the element matches its surrounding background without hardcoding a specific level.

```css
.searchBarContainer {
position: sticky;
top: 0;
background-color: var(--bui-bg-inherit);
}
```

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

### SearchAutocomplete with Rich Content Items

Source: https://ui.backstage.io/components/search-autocomplete

Shows how to render SearchAutocomplete items with rich content, including titles and descriptions. This example filters a list of fruits based on user input.

```jsx
const fruits = [
  { id: 'apple', name: 'Apple', description: 'A round fruit' },
  { id: 'banana', name: 'Banana', description: 'A yellow curved fruit' },
  { id: 'cherry', name: 'Cherry', description: 'A small red stone fruit' },
];

function Example() {
  const [inputValue, setInputValue] = useState('');

  const filtered = fruits.filter(fruit =>
    fruit.name.toLowerCase().includes(inputValue.toLowerCase()),
  );

  return (
    <SearchAutocomplete
      placeholder="Search fruits..."
      inputValue={inputValue}
      onInputChange={setInputValue}
    >
      {filtered.map(fruit => (
        <SearchAutocompleteItem
          key={fruit.id}
          id={fruit.id}
          textValue={fruit.name}
        >
          <Text weight="bold">{fruit.name}</Text>
          <Text variant="body-small" color="secondary">
            {fruit.description}
          </Text>
        </SearchAutocompleteItem>
      ))}
    </SearchAutocomplete>
  );
}
```

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

### BUIProvider Integration for Client-Side Routing

Source: https://ui.backstage.io/components/button-link

Example of integrating BUIProvider within a BrowserRouter to enable client-side navigation for components like ButtonLink. This is a breaking change introduced in version 0.13.0.

```javascript
import { BUIProvider } from '@backstage/ui';

<BrowserRouter>
  <BUIProvider>
    <AppContent />
  </BUIProvider>
</BrowserRouter>
```

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

### Avatar Purpose Prop Example

Source: https://ui.backstage.io/components/avatar

Illustrates the use of the `purpose` prop to control accessibility announcements for the avatar. Use 'informative' for standalone avatars and 'decoration' when adjacent text provides context.

```javascript
<Avatar purpose="informative" src="..." name="Charles de Dreuille" />
```

```javascript
<Avatar purpose="decoration" src="..." name="Charles de Dreuille" />
```

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

### Select Component Sizes

Source: https://ui.backstage.io/components/select

Illustrates the different visual sizes available for the Select component: 'small' and 'medium'. Use the 'size' prop to control the component's dimensions.

```jsx
<Flex>
  <Select
    size="small"
    label="Font family"
    options={[ ... ]}
  />
  <Select
    size="medium"
    label="Font family"
    options={[ ... ]}
  />
</Flex>
```

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

### CSS Tokens: Rename background surface to neutral

Source: https://ui.backstage.io/changelog

Migration guide for CSS token changes. Replaces old surface and gray scale tokens with new neutral scale tokens.

```css
- background: var(--bui-bg-surface-0);
+ background: var(--bui-bg-neutral-0);
```

```css
- background: var(--bui-bg-neutral-on-surface-0);
+ background: var(--bui-bg-neutral-1);
```

```css
- background: var(--bui-gray-1);
+ background: var(--bui-bg-neutral-1);
```

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

### ButtonLink with Icons

Source: https://ui.backstage.io/components/button-link

Shows how to add icons before, after, or both before and after the link text in a ButtonLink. Ensure you have the necessary icon components imported.

```javascript
<Flex align="center">
  <ButtonLink iconStart={<RiCloudLine />} href="https://ui.backstage.io" target="_blank">
    Button
  </ButtonLink>
  <ButtonLink iconEnd={<RiArrowRightSLine />} href="https://ui.backstage.io" target="_blank">
    Button
  </ButtonLink>
  <ButtonLink
    iconStart={<RiCloudLine />}
    iconEnd={<RiArrowRightSLine />}
    href="https://ui.backstage.io"
    target="_blank"
  >
    Button
  </ButtonLink>
</Flex>
```

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

### PluginHeader with Navigation Tabs

Source: https://ui.backstage.io/components/plugin-header

Configure navigation tabs for the PluginHeader. Tabs automatically highlight based on the current route, utilizing React Router. Ensure the `href` properties match your routing setup.

```javascript
<PluginHeader
  title="My plugin"
  titleLink="/"
  tabs={[
    { id: 'overview', label: 'Overview', href: '/overview' },
    { id: 'checks', label: 'Checks', href: '/checks' },
    { id: 'tracks', label: 'Tracks', href: '/tracks' },
    { id: 'campaigns', label: 'Campaigns', href: '/campaigns' },
    { id: 'integrations', label: 'Integrations', href: '/integrations' },
  ]} 
/>
```

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

### Table with Sorting Enabled

Source: https://ui.backstage.io/components/table

Example of configuring columns to be sortable. For `mode: 'complete'`, sorting is client-side and may require a `sortFn`. For server-side sorting with `offset` or `cursor` modes, refer to server-side data documentation.

```typescript
const columns: ColumnConfig<DataType>[] = [
  { id: 'name', label: 'Name', isRowHeader: true, cell: item => <CellText title={item.name} /> },
  { id: 'owner', label: 'Owner', isSortable: true, cell: item => <CellText title={item.owner} /> },
];

function MyTable() {
  const { tableProps } = useTable({
    mode: 'complete',
    data,
    initialSort: {
      id: 'name',
      direction: 'asc',
    },
  });

  return <Table columnConfig={columns} {...tableProps} />;
}
```
Tokens:
Raw