# ReferralBlock

A block of related-story cards (rendered as Referral children), fetching recent Reuters.com stories by section or taking supplied ones.

**Category:** Components/Page furniture/ReferralBlock

**Import:** `import { ReferralBlock } from '@reuters-graphics/graphics-components'`

## Props

| Prop | Type | Default | Required | Description |
|------|------|---------|:--------:|-------------|
| `section` | `string` | `'/world/'` |  | Section ID, which is often the URL path to the section page on reuters.com.  Note that not all section pages will be available in the recent stories by section API. Options: `/world/`, `/world/europe/`, `/lifestyle/`, `/lifestyle/sports/`, `/legal/`, `/business/`, `/business/energy/` |
| `collection` | `string` | — |  | Collection alias, as defined in Arc Collections editor. |
| `stories` | `ReferralItem[]` | `[]` |  | Provide your own referrals instead of fetching recent stories from Reuters.com. When set, the `section`/`collection` fetch is skipped and these stories are rendered as-is. |
| `number` | `number` | `4` |  | Number of referrals to show. Options: `2`, `4`, `6`, `8` |
| `linkTarget` | `LinkTarget` | `'_self'` |  | Link [target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target), e.g., `_blank` or `_parent`. |
| `heading` | `string` | `''` |  | Add a heading to the referral block. |
| `width` | `ReferralBlockWidth` | `'wide'` |  | Width of the component within the text well: 'normal' \| 'wide' \| 'wider' \| 'widest' \| 'fluid' Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
| `id` | `string` | `''` |  | Add an ID to target with SCSS. |
| `class` | `string` | `'fmy-5'` |  | Add a class to target with SCSS. |

## Examples

### Demo

```svelte
<ReferralBlock section="/lifestyle/sports/" class="fmy-0" heading="More World Cup coverage" />
```

### By collection

```svelte
<ReferralBlock collection="x-trump" number={6} class="fmy-8" heading="The latest Trump coverage" />
```

### Manual stories

```svelte
<ReferralBlock
  class="fmy-0"
  heading="Related coverage"
  stories={/* array — see Props/Types for full type */}
/>
```

## Documentation

# ReferralBlock

The `ReferralBlock` component creates a set of referral links from recent Reuters.com stories using the [recent stories by section API](https://www.reuters.com/pf/api/v3/content/fetch/recent-stories-by-sections-v1?query=%7B%22section_ids%22%3A%22%2Fworld%2F%22%2C%22size%22%3A20%2C%22website%22%3A%22reuters%22%7D).

> Note: The `section` or `collection` prop determines which section or collection stories are from.
>
> You can get the section ID from the URL for the Reuters.com section pages. For example, the section ID for [World - Europe](https://www.reuters.com/world/europe/) stories at `www.reuters.com/world/europe/` would be `/world/europe/`. (The leading and trailing slashes are required!)
>
> You should get the collection alias from the dotcom team.

```svelte
<script>
  import { ReferralBlock } from '@reuters-graphics/graphics-components';
</script>

<ReferralBlock
  section="/lifestyle/sports/"
  class="fmy-0"
  heading="More World Cup coverage"
/>
```

## Collections

TK - Check if this is still relevant.

```svelte
<script>
  import { ReferralBlock } from '@reuters-graphics/graphics-components';
</script>

<ReferralBlock collection="x-trump" number={6} class="fmy-8" />
```

## Manual stories

Pass a `stories` array to populate the block with your own one-off referrals
instead of fetching them over the wire. When `stories` is set, the
`section`/`collection` fetch is skipped entirely and your stories render as-is —
which also means they show up in any environment, not just production
`www.reuters.com`.

Each story matches the `ReferralItem` type. Only `url`, `kicker`, `title` and
`imageUrl` are required; `imageAlt` and `time` are optional (omit `time` to hide
the publish time).

```svelte
<script>
  import { ReferralBlock } from '@reuters-graphics/graphics-components';

  const stories = [
    {
      url: 'https://www.reuters.com/world/europe/',
      kicker: 'Europe',
      title: 'A hand-picked story you provide yourself',
      imageUrl: 'https://www.reuters.com/your-thumbnail.jpg',
      imageAlt: 'Describe the image',
      time: new Date('2026-06-16T12:00:00Z'),
    },
    {
      url: 'https://www.reuters.com/business/energy/',
      kicker: 'Energy',
      title: 'Another one-off referral with no publish time',
      imageUrl: 'https://www.reuters.com/another-thumbnail.jpg',
    },
  ];
</script>

<ReferralBlock {stories} heading="Related coverage" class="fmy-0" />
```

```
```