Primer

https://primer.style/
Admin
Primer is GitHub's comprehensive design system for building accessible and consistent user...
Tokens:789,837
Snippets:5,942
Trust Score:10
Update:12 minutes ago
Show doc for...
Tokens:
Raw
### Bundle install

Source: https://primer.style/octicons/code/

Run bundle install to install the gem.

```bash
bundle install
```

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

### Install @primer/react and peer dependencies

Source: https://primer.style/product/getting-started/react/

Install the required packages: @primer/react, @primer/primitives, react, and react-dom.

```bash
npm install @primer/react @primer/primitives react react-dom
```

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

### Primer::LocalTime usage example

Source: https://primer.style/product/getting-started/rails/migration-guides/primer-local-time/

Shows the original setup of the deprecated Primer::LocalTime component with datetime and initial_text arguments.

```erb
<%= Primer::LocalTime(datetime: Time.now, initial_text: Time.now.iso8601) %>
```

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

### Install @primer/primitives with npm

Source: https://primer.style/product/primitives/

Install the Primer Primitives package using npm.

```bash
npm install @primer/primitives
```

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

### Popover Default Example

Source: https://primer.style/product/components/popover/

A basic example showing how to render a Popover with its content using the Popover and Popover.Content components.

```APIDOC
## Popover Default Example

### Description
Renders a Popover with its content. The `relative` prop is set to true to use relative positioning, and `open` is set to true to show the popover.

### Example
```jsx
<Popover relative open>
  <Popover.Content>Popover content</Popover.Content>
</Popover>
```
```

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

### Install @primer/octicons-react

Source: https://primer.style/octicons/code/

Install the React Octicons package via npm.

```bash
npm install @primer/octicons-react
```

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

### Install @primer/primitives with yarn

Source: https://primer.style/product/primitives/

Install the Primer Primitives package using yarn.

```bash
yarn add @primer/primitives
```

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

### Install eslint-plugin-primer-react with npm or yarn

Source: https://primer.style/product/getting-started/react/linting/

Run one of these commands to install the plugin as a dev dependency. The plugin is experimental; report issues in the primer/react repository.

```bash
npm install --save-dev eslint-plugin-primer-react

# or

yarn add --dev eslint-plugin-primer-react
```

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

### VS Code MCP server configuration for Primer

Source: https://primer.style/product/getting-started/foundations/mcp/

Configuration for the Primer MCP server in VS Code. Install via Command Palette with 'MCP: Install Server', select 'stdio', enter 'npx @primer/mcp@latest', and name it 'Primer'.

```json
{
  "servers": {
    "Primer": {
      "type": "stdio",
      "command": "npx",
      "args": ["@primer/mcp@latest"]
    }
  },
  "inputs": []
}
```

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

### Text component example with size and weight props

Source: https://primer.style/product/components/text/

This example is currently non-functional until @primer/react is upgraded to support the size and weight props. It shows a span element with a note about the upgrade requirement.

```html
<span>
  This example will not work until we have upgrade `@primer/react` to a version that supports the `size` and `weight`
  props
</span>
```

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

### Default Card with Icon, Heading, Description, and Metadata

Source: https://primer.style/product/components/card/

Basic Card example with an icon, heading, description, and metadata. The Card renders a div by default. The example is wrapped in a div with maxWidth 400px.

```jsx
<div style={{maxWidth: '400px'}}>
  <Card>
    <Card.Icon icon={RocketIcon} />
    <Card.Heading>Card Heading</Card.Heading>
    <Card.Description>This is a description of the card providing supplemental information.</Card.Description>
    <Card.Metadata>
      <PeopleIcon size={16} /> 3 contributors
    </Card.Metadata>
  </Card>
</div>
```

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

### Sidebar placement with Primer::Alpha::Layout (start positions)

Source: https://primer.style/product/getting-started/rails/migration-guides/primer-layout-component/

Migrated example using `col_placement: :start` and `row_placement: :start` to place the sidebar at the start in both column and row modes. To keep the sidebar below the main content, use `row_placement: :end`; to hide it entirely, use `row_placement: :none`.

```erb
<%= render(Primer::Alpha::Layout.new) do |component| %>
  <% component.with_main { "Main" } %>
  <% component.with_sidebar(col_placement: :start, row_placement: :start) { "Sidebar" } %>
<% end %>
```

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

### Original details-dialog example

Source: https://primer.style/product/getting-started/rails/migration-guides/primer-dialog/

Shows a details-dialog with a danger button, flash message, and action list. This is the starting point for migration.

```erb
<details class="float-right" id="confirm-submit">
  <%= render Primer::ButtonComponent.new(tag: :summary, scheme: :danger) do %> Continue with step <% end %>
  <details-dialog class="anim-fade-in fast Box Box--overlay d-flex flex-column">
    <div class="Box-header">
      <button class="Box-btn-octicon btn-octicon float-right" type="button" aria-label="Close Dialog" data-close-dialog>
        <%= primer_octicon(:x) %>
      </button>
      <h3 class="Box-title">Do you want to continue with this action?</h3>
    </div>

    <%= render(Primer::Beta::Flash.new(scheme: :danger, full: true, icon: "alert")) do %> Please follow all steps listed
    below. <% end %>
    <div class="Box-body overflow-auto">
      <ul class="mb-3 ml-3">
        <li>Step 1: Do action</li>
        <li>Step 2: Do second action</li>
        <li>Step 3: Do third action</li>
      </ul>
      <%= render Primer::ButtonComponent.new(block: true, scheme: :danger, "data-close-dialog": "", "data-toggle-for":
      "continue-action") do %> I understand, continue <% end %>
    </div>
  </details-dialog>
</details>
```

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

### Sidebar at Start with PageLayout.Sidebar

Source: https://primer.style/product/components/page-layout/

Use this example to create a full-height sidebar that spans adjacent to the header, content, and footer. The parent element must fill the viewport for the sidebar to span the full page height. The sidebar is placed at the start position with a width range from 100px to 200px.

```tsx
import React from 'react'
import {PageLayout} from '@primer/react'


function Placeholder({height, children}: {height: number | string; children: React.ReactNode}) {
  return (
    <div
      style={{
        width: '100%',
        height,
        display: 'grid',
        placeItems: 'center',
        backgroundColor: 'var(--bgColor-inset)',
        borderRadius: 'var(--borderRadius-medium)',
        border: '1px solid var(--borderColor-muted)',
      }}
    >
      {children}
    </div>
  )
}


export default function SidebarStart() {
  return (
    <PageLayout>
      <PageLayout.Sidebar width={{min: '100px', default: '200px', max: '200px'}}>
        <Placeholder height={528}>Sidebar</Placeholder>
      </PageLayout.Sidebar>
      <PageLayout.Header>
        <Placeholder height={64}>Header</Placeholder>
      </PageLayout.Header>
      <PageLayout.Content>
        <Placeholder height={400}>Content</Placeholder>
      </PageLayout.Content>
      <PageLayout.Footer>
        <Placeholder height={64}>Footer</Placeholder>
      </PageLayout.Footer>
    </PageLayout>
  )
}
```

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

### useColorSchemeVar example

Source: https://primer.style/product/hooks/useColorSchemeVar/

Use this hook to get a string value based on the active color scheme. The example passes an object mapping 'light' and 'dark' to 'day' and 'night', with a fallback 'other'. The returned value is displayed in a span. The hook should not be used to create custom color schemes.

```jsx
import React from 'react'
import {useColorSchemeVar} from '@primer/react'


export default function Default() {
  const colorSchemeVar = useColorSchemeVar({light: 'day', dark: 'night'}, 'other')


  return <span>Color scheme alias: {colorSchemeVar}</span>
}
```

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

### Custom Size Avatar React Example

Source: https://primer.style/product/components/avatar/

Sets the avatar size to 48px. Avatars start at 16px and increment by base-4 until 32px, then switch to base-8 up to 48px; 64px is the largest size.

```jsx
<Avatar size={48} src="https://avatars.githubusercontent.com/u/92997159?v=4" alt="Mona user avatar" />
```

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

### Preview URL for Primer::Beta::IconButtonPreview link_as_button scenario

Source: https://primer.style/view-components/lookbook/inspect/primer/beta/icon_button/link_as_button/

Direct URL to the Lookbook preview for the link_as_button scenario. Use this to open the preview in a new window.

```URL
https://primer.style/view-components/lookbook/embed?props=%7B%22preview%22%3A%22Primer%3A%3ABeta%3A%3AIconButtonPreview%22%2C%22scenario%22%3A%22link_as_button%22%7D
```

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

### AnchoredOverlay with predefined width and height

Source: https://primer.style/product/components/anchored-overlay/

Customizes the overlay size using the width="small" and height="xsmall" props. The rest of the setup matches the default example.

```jsx
import React from 'react'
import {AnchoredOverlay, Button, Stack} from '@primer/react'


export default function WidthHeightCustom() {
  const [open, setOpen] = React.useState(false)


  return (
    <AnchoredOverlay
      open={open}
      onOpen={() => setOpen(true)}
      onClose={() => setOpen(false)}
      renderAnchor={props => <Button {...props}>Toggle overlay</Button>}
      width="small"
      height="xsmall"
    >
      <Stack padding="spacious">
        Anchored overlay content
        <Button
          block
          onClick={() => {
            setOpen(false)
          }}
        >
          Close
        </Button>
      </Stack>
    </AnchoredOverlay>
  )
}
```

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

### Partially visually hidden accessible names for Get started links

Source: https://primer.style/accessibility/design-guidance/links-and-buttons/

Append sr-only text to the end of the accessible name to distinguish multiple controls with the same visible prefix. Note the space after the closing > of the first span to prevent words from being combined by assistive technology.

```html
<a href="https://github.com/github/primer/issues/new/">
  Get started<span class="sr-only"> with a pattern proposal</span>
</a>

<a href="https://github.com/github/primer/issues/new/">
  Get started<span class="sr-only"> with a bug report</span>
</a>
```

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

### Directory structure example

Source: https://primer.style/view-components/lookbook/pages/forms/getting_started/

Shows the recommended directory structure for form classes, mirroring the controllers directory. Place form classes under app/forms/.

```text
app
  ╵─ controllers
     ╵─ settings
        ╵─ email_notifications_controller.rb
  ╵─ forms
     ╵─ settings
        ╵─ email_notifications
           ╵─ config_form.rb
```

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

### Settings Page with Danger Zone using SplitPageLayout

Source: https://primer.style/product/components/split-page-layout/

Example of a settings page layout with a sidebar navigation pane and a danger zone content area. Uses SplitPageLayout.Pane with position="start" for the NavList and SplitPageLayout.Content for the main content. Includes a danger-styled heading, a bordered container with delete account text, and a danger button.

```jsx
<SplitPageLayout>
  <SplitPageLayout.Pane position="start">
    <NavList aria-label="Main navigation">
      <NavList.Item href="#">Profile</NavList.Item>
      <NavList.Item href="#" aria-current="page">
        Account
      </NavList.Item>
      <NavList.Item href="#">Emails</NavList.Item>
      <NavList.Item href="#">Notifications</NavList.Item>
    </NavList>
  </SplitPageLayout.Pane>
  <SplitPageLayout.Content>
    <Heading
      as="h2"
      style={{
        fontSize: '2em',
        fontWeight: 'normal',
        color: 'var(--fgColor-danger,var(--color-danger-fg,#d1242f))',
        marginBottom: '1rem',
      }}
    >
      Danger zone
    </Heading>
    <div
      style={{
        border: '1px solid',
        borderColor: 'var(--borderColor-danger-emphasis,var(--color-danger-emphasis,#cf222e))',
        borderRadius: '1rem',
        padding: '1rem',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'space-between',
        gap: '1rem',
      }}
    >
      <div style={{display: 'grid', gap: '1rem'}}>
        <p
          style={{
            fontSize: '1em',
            fontWeight: 'bold',
            color: 'var(--fgColor-danger,var(--color-danger-fg,#d1242f))',
          }}
        >
          Delete account
        </p>
        <p style={{fontSize: '1em', color: 'var(--fgColor-muted,var(--color-fg-muted,#6a737d))'}}>
          Are you sure you don&apos;t want to just downgrade your account to a free account? We won&apos;t charge your
          credit card anymore.
        </p>
      </div>
      <Button variant="danger">Delete account</Button>
    </div>
  </SplitPageLayout.Content>
</SplitPageLayout>
```

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

### Wrap app with ThemeProvider and BaseStyles

Source: https://primer.style/product/getting-started/react/

Import the light theme CSS and wrap the root component with ThemeProvider and BaseStyles. This is required for Primer React components to work.

```jsx
// Import each of the themes you would like to use, by default we are including
// the light theme below
import '@primer/primitives/dist/css/functional/themes/light.css'
import {BaseStyles, ThemeProvider} from '@primer/react'

function RootLayout() {
  return (
    <ThemeProvider>
      <BaseStyles>
        <App />
      </BaseStyles>
    </ThemeProvider>
  )
}
```

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

### useSlots Example with ActionList

Source: https://primer.style/product/hooks/useSlots/

Example showing how to use useSlots to extract leadingVisual and description slots from children, and a consumer example. The hook is imported from the internal path '@primer/react/hooks'.

```jsx
import {useSlots} from '@primer/react/hooks'   // internal import path
import {ActionList} from '@primer/react'

function StatusRow({children}) {
  const [slots, rest] = useSlots(children, {
    leadingVisual: ActionList.LeadingVisual,
    description:   ActionList.Description,
  })

  return (
    <li>
      {slots.leadingVisual}
      <span>{rest}</span>
      {slots.description}
    </li>
  )
}

// Consumer
<StatusRow>
  <ActionList.LeadingVisual>✅</ActionList.LeadingVisual>
  Approved
  <ActionList.Description>Status detail</ActionList.Description>
</StatusRow>
```

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

### Full React example of `as` prop demo

Source: https://primer.style/product/getting-started/react/extending-components/

A complete React component demonstrating the `as` prop with three Button variants inside a Stack layout. Includes imports from @primer/react and @primer/octicons-react.

```jsx
import React from 'react'
import {Button, Stack, Text} from '@primer/react'
import {LinkExternalIcon} from '@primer/octicons-react'


// Three renderings of the same Button component, varying only the `as` prop.
// All three inherit the Button's styling, focus ring, padding, etc., but the
// underlying DOM element changes.
export default function AsPropDemo() {
  return (
    <Stack direction="horizontal" gap="normal" align="stretch">
      <Stack.Item grow>
        <Text as="p" size="small" weight="semibold">
          Default (button)
        </Text>
        <Button>Submit form</Button>
      </Stack.Item>


      <Stack.Item grow>
        <Text as="p" size="small" weight="semibold">
          as="a"
        </Text>
        <Button as="a" href="https://primer.style" trailingVisual={LinkExternalIcon}>
          Visit Primer
        </Button>
      </Stack.Item>


      <Stack.Item grow>
        <Text as="p" size="small" weight="semibold">
          as="summary"
        </Text>
        <details>
          <Button as="summary">Toggle details</Button>
          <p style={{margin: 'var(--base-size-8) 0 0'}}>Hidden details revealed by the summary.</p>
        </details>
      </Stack.Item>
    </Stack>
  )
}
```

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

### Responsive flex utility example classes

Source: https://primer.style/product/css-utilities/flexbox/

Example classes showing the responsive flex utility naming formulas: `d-[breakpoint]-[property]` for display and `flex-[breakpoint]-[property]-[behavior]` for flex properties. Each responsive style applies to the specified breakpoint and up.

```CSS
/* Example classes */

.d-sm-flex {
}
.d-md-inline-flex {
}

.flex-lg-row {
}
.flex-xl-column {
}

.flex-sm-wrap {
}
.flex-lg-nowrap {
}

.flex-lg-self-start {
}
```

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

### Source code for Primer::Alpha::IncludeFragment default scenario

Source: https://primer.style/view-components/lookbook/inspect/primer/alpha/include_fragment/default/

Renders the IncludeFragment component with eager loading and a source URL, displaying 'Loading...' as the fallback content.

```ruby
render(Primer::Alpha::IncludeFragment.new(loading: :eager, src: UrlHelpers.primer_view_components.include_fragment_deferred_path)) { "Loading..." }
```

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

### CheckBox Usage Example

Source: https://primer.style/view-components/lookbook/pages/forms/inputs/check_box/

Example of using the check_box method within an ApplicationForm form builder, including a nested form.

```APIDOC
## CheckBox Usage

### Description
Example of using the `check_box` method within an `ApplicationForm` form builder, including a nested form.

### Method
`check_box`

### Arguments
- `attributes` (Hash) - Required - Attributes for the check box.

### Example
```ruby
class ExampleForm < ApplicationForm
  form do |example_form|
    example_form.check_box(attributes) do |check_box|
      check_box.nested_form do |builder|
        AnotherPrimerForm.new(builder)
      end
    end
  end
end
```
```

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

### Primer Select Component Arguments

Source: https://primer.style/product/getting-started/rails/components/select/

Lists all arguments accepted by the Primer Select component, with their types, defaults, and descriptions.

```APIDOC
## Primer Select Component Arguments

### Description
This component accepts a variety of arguments to customize its behavior and appearance.

### Arguments

| Name | Default | Description |
| --- | --- | --- |
| `size` | | `Symbol` - The size of the field. One of `:large`, `:medium`, or `:small`. |
| `name` | | `String` - Value for the HTML name attribute. |
| `id` | | `String` - Value for the HTML id attribute. |
| `class` | | `String` - CSS classes to include in the input's HTML `class` attribute. Exists for compatibility with Rails form builders. |
| `classes` | | `Array` - CSS classes to include in the input's HTML `class` attribute. Combined with the `:class` argument. The list may contain strings, hashes, or `nil` values, and is automatically cleaned up by Primer's `class_name` helper (`nils`, falsy entries, and blank strings are ignored). |
| `caption` | | `String` - A string describing the field and what sorts of input it expects. Displayed below the input. |
| `label` | | `String` - Label text displayed above the input. |
| `visually_hide_label` | | `Boolean` - When set to `true`, hides the label. Although the label will be hidden visually, it will still be visible to screen readers. |
| `disabled` | | `Boolean` - When set to `true`, the input will not accept keyboard or mouse input. |
| `hidden` | | `Boolean` - When set to `true`, visually hides the field. |
| `invalid` | | `Boolean` - If set to `true`, the input will be rendered with a red border. Implied if `validation_message` is truthy. This option is set to `true` automatically if the model object associated with the form reports that the input is invalid via Rails validations. It is provided for cases where the form does not have an associated model. If the input is invalid as determined by Rails validations, setting `invalid` to `false` will have no effect. |
| `validation_message` | | `String` - A string displayed between the caption and the input indicating the input's contents are invalid. This option is, by default, set to the first Rails validation message for the input (assuming the form is associated with a model object). Use `validation_message` to override the default or to provide a validation message in case there is no associated model object. |
| `label_arguments` | | `Hash` - Attributes that will be passed to Rails' `builder.label` method. These can be HTML attributes or any of the other label options Rails supports. They will appear as HTML attributes on the `<label>` tag. |
| `scope_name_to_model` | | `Boolean` - Default `true`. When set to `false`, prevents the model name from prefixing the field name. For example, if the field name is `my_field`, Rails will normally emit an HTML name attribute of `model[my_field]`. Setting `scope_name_to_model` to `false` will cause Rails to emit `my_field` instead. |
| `scope_id_to_model` | | `Boolean` - Default `true`. When set to `false`, prevents the model name from prefixing the field ID. For example, if the field name is `my_field`, Rails will normally emit an HTML ID attribute of `model_my_field`. Setting `scope_id_to_model` to `false` will cause Rails to emit `my_field` instead. |
| `required` | | `Boolean` - Default `false`. When set to `true`, causes an asterisk (\*) to appear next to the field's label indicating it is a required field. Note that this option explicitly does _not_ add a `required` HTML attribute. Doing so would enable native browser validations, which are inaccessible and inconsistent with the Primer design system. |
| `aria` | | `Hash` - Key/value pairs that represent Aria attributes and their values. Eg. `aria: { current: true }` becomes `aria-current="true"`. |
| `data` | | `Hash` - Key/value pairs that represent data attributes and their values. Eg. `data: { foo: "bar" }` becomes `data-foo="bar"`. |
| `system_arguments` | | `Hash` - A hash of attributes passed to the underlying Rails builder methods. These options may mean something special depending on the type of input, otherwise they are emitted as HTML attributes. See the Rails documentation for more information. In addition, the usual Primer utility arguments are accepted in system arguments. For example, passing `mt: 2` will add the `mt-2` class to the input. See the Primer system arguments docs for details. |
| `multiple` | | `Boolean` - If set to true, the selection will allow multiple choices. |
| `include_blank` | | `Boolean, String` - If set to true, an empty option will be created. If set to a string, the string will be used as the option's content and the value will be empty. |
| `prompt` | | `String` - Create a prompt option with blank value and the text asking user to select something. |
```

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

### Good vs. Avoid: ConfirmationDialog title examples

Source: https://primer.style/product/components/confirmation-dialog/accessibility/

Shows specific and clear titles versus vague or generic titles. The good example includes a descriptive title and content explaining the consequences. The avoid example uses a generic title and lacks context.

```jsx
// Good: Specific and clear
<ConfirmationDialog title="Delete repository?">
  This action cannot be undone. This will permanently delete the "my-repo" repository.
</ConfirmationDialog>

// Avoid: Vague or generic
<ConfirmationDialog title="Are you sure?">
  This action cannot be undone.
</ConfirmationDialog>
```

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

### useSafeTimeout example with alert and cancel

Source: https://primer.style/product/hooks/useSafeTimeout/

Example usage of useSafeTimeout from @primer/react. The hook returns safeSetTimeout and safeClearTimeout. The example sets a timeout to show an alert after 3 seconds and provides a cancel button. The timeoutId is stored in a variable and used to conditionally render the cancel button.

```tsx
import React from 'react'
import {useSafeTimeout} from '@primer/react'


export default function Default() {
  const {safeSetTimeout, safeClearTimeout} = useSafeTimeout()
  let timeoutId: number | null = null


  const handleOnClick = () => {
    timeoutId = safeSetTimeout(() => window.alert('Hello!'), 3000)
  }


  const cancelTimeout = () => {
    if (timeoutId) {
      safeClearTimeout(timeoutId)
    }
  }


  return (
    <div style={{display: 'flex', gap: '1rem'}}>
      <button onClick={handleOnClick}>Show alert after 3 seconds</button>
      {timeoutId ?? <button onClick={cancelTimeout}>Cancel alert</button>}
    </div>
  )
}
```

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

### Preview URL for UnderlinePanels with actions

Source: https://primer.style/view-components/lookbook/inspect/primer/alpha/underline_panels/with_actions/

URL to directly open the preview of the UnderlinePanels component with the 'with_actions' scenario.

```text
https://primer.style/view-components/lookbook/embed?props=%7B%22preview%22%3A%22Primer%3A%3AAlpha%3A%3AUnderlinePanelsPreview%22%2C%22scenario%22%3A%22with_actions%22%7D
```

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

### Import complete Primer CSS for base styles

Source: https://primer.style/product/getting-started/react/

Import the full Primer CSS to get base HTML element styling that matches GitHub.com, such as link colors.

```javascript
import '@primer/css/dist/primer.css'
```

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

### Default SkeletonBox usage

Source: https://primer.style/product/components/skeleton-box/

Renders a SkeletonBox with width and height set to 200 pixels. This is the default example from the React examples section.

```jsx
<SkeletonBox width={200} height={200} />
```

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

### GitHub Copilot CLI MCP server configuration for Primer

Source: https://primer.style/product/getting-started/foundations/mcp/

Configuration for the Primer MCP server in GitHub Copilot CLI, placed in either .mcp.json or .github/mcp.json.

```json
{
  "mcpServers": {
    "Primer": {
      "type": "stdio",
      "command": "npx",
      "args": ["@primer/mcp@latest"]
    }
  }
}
```
Tokens:
Raw