RankedList

Server component, no client JS

ImportCopy Anchor Link

import { RankedList } from '@nizivo/react/ranked-list';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/card.css and @nizivo/react/css/inline-error.css and @nizivo/react/css/number-value.css and @nizivo/react/css/skeleton.css
import '@nizivo/react/css/ranked-list.css';

Static or interactiveCopy Anchor Link

Server. It ships no client JavaScript when a Server Component renders it, in every Next.js build mode; its code is bundled only when a client component (a 'use client' file) imports it. The bars are SVG with percentage widths, so the server HTML has no style attribute. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

ExamplesCopy Anchor Link

import type { ComponentPropsWithRef, JSX } from 'react';
import { RankedList } from '@nizivo/react/ranked-list';

/** Stands in for a router link (Next `Link`, React Router `Link`). */
function Link({ children, ...props }: ComponentPropsWithRef<'a'>): JSX.Element {
  return <a {...props}>{children}</a>;
}

const CHANNELS = [
  ['Online store', 64120],
  ['Instagram Shop', 21804],
  ['Wholesale', 18240],
  ['Pop-up market', 9312],
  ['Marketplace', 6050],
] as const;

const USD = { style: 'currency', currency: 'USD', maximumFractionDigits: 0 } as const;

export function RankedListExample(): JSX.Element {
  return (
    <RankedList.Root
      title="Top channels"
      action={<RankedList.Action render={<Link href="/channels" />}>View all</RankedList.Action>}
      format={USD}
    >
      {CHANNELS.map(([label, value]) => (
        <RankedList.Item key={label} label={label} value={value} />
      ))}
    </RankedList.Root>
  );
}

import type { JSX } from 'react';
import { RankedList } from '@nizivo/react/ranked-list';

export function RankedListStatesExample(): JSX.Element {
  return (
    <div>
      <RankedList.Root title="Top channels" status="loading" />
      <RankedList.Root title="Top cities" status="empty" />
      <RankedList.Root title="Top products" status="error" />
    </div>
  );
}

Other exportsCopy Anchor Link

RankedListActionProps type

import type { RankedListActionProps } from '@nizivo/react/ranked-list'

The props of RankedList.Action, listed above.

RankedListItemProps type

import type { RankedListItemProps } from '@nizivo/react/ranked-list'

The props of RankedList.Item, listed above.

RankedListItemState type

import type { RankedListItemState } from '@nizivo/react/ranked-list'

The render state of RankedList.Item, listed above.

RankedListLabels type

import type { RankedListLabels } from '@nizivo/react/ranked-list'

RankedList's own strings (§16.4): serialisable, English defaults, Metric's wording. {label} is replaced by the title (left out when there is none).

Name	Type	Default	Description
emptyrequired	string	'No data'	Shown when there is nothing to rank and no empty slot.
errorrequired	string	'Could not load {label}'	The InlineError message on a load failure with no error slot.
loadingrequired	string	'Loading {label}'	Static, visually hidden text while loading (§16.5: no live region).

RankedListRootProps type

import type { RankedListRootProps } from '@nizivo/react/ranked-list'

The props of RankedList.Root, listed above.

RankedListRootState type

import type { RankedListRootState } from '@nizivo/react/ranked-list'

The render state of RankedList.Root, listed above.

RankedListTitleLevel type

import type { RankedListTitleLevel } from '@nizivo/react/ranked-list'

type RankedListTitleLevel = 2 | 3 | 4 | 5 | 6

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-card, .nz-ranked-list, .nz-ranked-list-action, .nz-ranked-list-bar, .nz-ranked-list-empty, .nz-ranked-list-fill, .nz-ranked-list-header, .nz-ranked-list-item, .nz-ranked-list-label, .nz-ranked-list-list, .nz-ranked-list-message, .nz-ranked-list-placeholder, .nz-ranked-list-reserve, .nz-ranked-list-row, .nz-ranked-list-skeleton-label, .nz-ranked-list-skeleton-value, .nz-ranked-list-status, .nz-ranked-list-title, .nz-ranked-list-track, .nz-ranked-list-value.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• ranked-list-action: draws the focus outline itself on keyboard focus.

KeyboardCopy Anchor Link

Source: a native <a> (RankedListAction in ranked-list.tsx, no client code), at least 24 px tall (WCAG 2.5.8).

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 752:444
• Ghost masters: none