---
title: "Rail — React"
canonical: https://sky-ui.cf.sky.com/components/rail/react
apiPackages: [{"name":"@sky-uk/ui-core","representedVersion":"13.2.0"}]
---

# Rail — React

Shows a vast variety of visual content that is connected by a common theme

```js
import { Rail } from '@sky-uk/ui-core';
```

The `Rail` component provides you with an horizontal scrolling list of content.

**Important:** **Note:** The `Rail` component **must not be placed inside of any container** to ensure that it
    spans the full width of the viewport. The width of the rail is controlled by the `$size` prop
    (see below).

```full-screen-react-live
<Rail $scrollableRegionTabIndex $railItemsLabel="additional description">
  <Rail.Heading>Learn more about Mary & George</Rail.Heading>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
</Rail>
```

## Props

### Rail

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| $appearance | string | undefined | The appearance of the heading. `'default'` \| `'light'` |
| $itemWidth | number | {xs: 280, lg: 300} | The width of each item in the rail. This prop is [responsive](/core/hooks/use-responsive-props/) and can be used to set the width of each item at different breakpoints. |
| $paginationPlacement | string | undefined | The position of the pagination. `'top'` \| `'bottom'`<br>Setting `$paginationPlacement="bottom"` results in the `Heading` being disabled |
| $railItemsLabel | string | undefined | A label for the rail items. This is used for accessibility purposes. |
| $scrollableRegionTabIndex | boolean | false | If set, the rail will be focusable. This is used for accessibility purposes.<br>Note: this prop should only be used if the rail has non-interactive content. |
| $size | string | 10-col | The size of the rail [container](/components/container/). This prop is [responsive](/core/hooks/use-responsive-props/) and can be used to set the size of the rail at different breakpoints. |
| $subGridTemplateRows | string | undefined | The template rows for the subgrid. See MDN for more information on [grid-template-rows](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows). |
| $subGridRow | string | undefined | The row for the subgrid. See MDN for more information on [grid-row](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row). |
| $theme | string | undefined | The theme of the heading as a Sky [gradient](/foundations/gradients/)<br>Note: if `$appearance` is set to `light`, the theme will be ignored. |

### Rail.Heading

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| $fontSize | string | { xs: 'display-6', md: 'display-5', lg: 'display-4' } | The font size of the heading. This prop is [responsive](/core/hooks/use-responsive-props/) and can be used to set the [typography](/foundations/typography/) of the heading at different breakpoints. |
| $textAlign | string | left | The text alignment of the heading. This prop is [responsive](/core/hooks/use-responsive-props/) and can be used to set the alignment of the heading at different breakpoints. |

---

## Callbacks

| Callback | Type | Returns |
| --- | --- | --- |
| onPaginate | string | `next` or `previous` when a pagination button is clicked |

## Functions

Function can used by the `Rail` component to programmatically scroll to the next or previous item in the rail.
Use the `ref` prop to get a reference to the `Rail` component and call the function on the reference.

| Function | Action |
| --- | --- |
| moveNext | Scrolls the Rail to the next slide |
| movePrevious | Scrolls the Rail to the previous slide |

## Basic Rail

```full-screen-react-live
<Rail $size="8-col" $railItemsLabel="additional description">
  <Rail.Heading $theme="sky" $alignment={{xs: 'left', lg: 'center'}} $fontSize={{xs: 'body-lg', lg: 'display-4'}}>Learn more about Mary & George</Rail.Heading>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
</Rail>
```

---

## Light variant

The Rail component is primarily a wrapper for custom components and can be displayed on a light or dark background. Applying the `$appearance` to `light` on the `Rail.Heading` will provide contrast on shaded backgrounds.

```full-screen-react-live-dark
<Rail $size="10-col" itemWidth={{ xs: 200, lg: 300 }} $appearance="light" $scrollableRegionTabIndex>
  <Rail.Heading>Learn more about Mary & George</Rail.Heading>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
</Rail>
```

---

## Using subgrid

The Rail component supports the use of subgrid to create a more complex layout. The `subGridRow` and `subGridTemplateRows` props can be used to control the layout of the subgrid. These props are applied to the `Rail.Item` and the first child of the `Rail.Item`.

```full-screen-react-live
<Rail $size="10-col" $subGridRow="span 3" $subGridTemplateRows="1fr auto auto" $scrollableRegionTabIndex>
  <Rail.Heading $appearance="light">Learn more about Mary & George</Rail.Heading>
  <Rail.Item>
    <Box $gap={{ xs: 3, lg: 4 }}>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" $gridRow="1" />
      <Text $display="inline-block" $fontWeight="bold" $gridRow="2">Header</Text>
      <Text $display="inline-block" $gridRow="3">Description</Text>
    </Box>
  </Rail.Item>
  <Rail.Item>
    <Box $gap={{ xs: 3, lg: 4 }}>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" $gridRow="1" />
      <Text $display="inline-block" $gridRow="3">Description</Text>
    </Box>
  </Rail.Item>
  <Rail.Item>
    <Box $gap={{ xs: 3, lg: 4 }}>
      <Text $display="inline-block" $fontWeight="bold" $gridRow="2">Header</Text>
      <Text $display="inline-block" $gridRow="3">Description</Text>
    </Box>
  </Rail.Item>
  <Rail.Item>
    <Box $gap={{ xs: 3, lg: 4 }}>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" $gridRow="1" />
      <Text $display="inline-block" $fontWeight="bold" $gridRow="2">Header</Text>
    </Box>
  </Rail.Item>
  <Rail.Item>
    <Box $gap={{ xs: 3, lg: 4 }}>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" $gridRow="1" />
      <Text $display="inline-block" $fontWeight="bold" $gridRow="2">Header</Text>
      <Text $display="inline-block" $gridRow="3">Description</Text>
    </Box>
  </Rail.Item>
</Rail>
```

---

## Pagination Placement

```full-screen-react-live
<Rail $size="8-col" $railItemsLabel="additional description" $paginationPlacement="bottom" $scrollableRegionTabIndex>
  <Rail.Heading $theme="sky" $alignment={{xs: 'left', lg: 'center'}} $fontSize={{xs: 'body-lg', lg: 'display-4'}}>Learn more about Mary & George</Rail.Heading>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
  <Rail.Item>
    <Card>
      <Image src="https://placehold.co/400x300" $aspectRatio="4 / 3" $width="100%" />
      <Box $padding={5}>
        <Text>Read our episode guide</Text>
      </Box>
    </Card>
  </Rail.Item>
</Rail>
```

---

## Translatable Fields

The `Rail` support translation on the following fields:

- `rail.previous.label` - controls the descriptive text for the previous item action
- `rail.next.label` - controls the descriptive text for the next item action

For more on translatable fields, view the `useTranslation` docs here: [useTranslation](/core/hooks/use-translation/)