Lists

note

Lists are rendered with an internal renderer. See Rendering page. The content model of lists is block, see Element Models.

tip

Lists marker rendering logic has been extracted to @jsamr/react-native-li and @jsamr/counter-style libraries for convinience! Fell free to use these outside of a RenderHTML component.

List Style Type#

List elements support list-style-type CSS property, which defines how the marker pseudo-element of a list item should be rendered. In CSS terminology, a marker is a pseudo-element situated before elements with a display property set to list-item. See CSS Lists and Counters Module Level 3 for a standard reference and DefaultSupportedListStyleType for a list of types supported by this library.

Ordered Lists#

Ordered lists <ol> elements support by default 6 list style types:

decimal: 1, 2, 3 ... (the default)
lower-alpha: a, b, c ...
upper-alpha: A, B, C ...
lower-greek: α, β, γ ...
lower-roman: i, ii, iii ...
upper-roman: I, II, III ...

Upper Roman List Style Type

JSX Source
HTML Snippet
TRT Snapshot

import React from 'react';
import { useWindowDimensions } from 'react-native';
import RenderHtml from 'react-native-render-html';

const source = {
  html: `<ol style="list-style-type: upper-roman; color: blue; font-weight: bold;">
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
  <li>Four</li>
  <li>Five</li>
  <li>Six</li>
  <li>Seven</li>
  <li>Eight</li>
</ol>`
};

export default function App() {
  const { width } = useWindowDimensions();
  return (
    <RenderHtml
      contentWidth={width}
      source={source}
    />
  );
}

Notice how marker pseudo-elements will inherit from the styles of the <ol> tag.

Press on the button below to show how this code renders on your device.

tip

You can actually very easily plug-in one of the dozens presets from @jsamr/counter-style, including Persian, Arabic, Hebrew, Thai, Katana... see the below chapter.

Unordered Lists#

Unordered lists <ul> elements support by default 5 list style types:

disc: "•" (the default)
square: "■"
circle: "○"
disclosure-open: "▼"
disclosure-closed: "▶"

note

Those markers are not rendered with UTF-8 characters, which might have a significant variety of shapes and sizes depending on fonts. Instead, geometric shapes are rendered.

Square List Style Type

JSX Source
HTML Snippet
TRT Snapshot

import React from 'react';
import { useWindowDimensions } from 'react-native';
import RenderHtml from 'react-native-render-html';

const source = {
  html: `<ul style="list-style-type: square;">
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
  <li>Four</li>
  <li>Five</li>
  <li>Six</li>
  <li>Seven</li>
  <li>Eight</li>
</ul>`
};

export default function App() {
  const { width } = useWindowDimensions();
  return (
    <RenderHtml
      contentWidth={width}
      source={source}
    />
  );
}

Press on the button below to show how this code renders on your device.

Defining and Customizing Markers Pseudo-Elements#

Using a Preset from @jsamr/counter-style#

The customListStyleSpecs prop allows you to create as many list type styles as you wish. Combined with the power of @jsamr/counter-style, you can plug-in one of the dozens of presets with a one-liner! See below example with the Thai preset:

Thai List Style Type

JSX Source
HTML Snippet
TRT Snapshot

import React from 'react';
import { useWindowDimensions } from 'react-native';
import RenderHtml from 'react-native-render-html';
import thaiCounterStyle from '@jsamr/counter-style/presets/thai';

const source = {
  html: `<ul style="list-style-type: thai;">
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
  <li>Four</li>
  <li>Five</li>
  <li>Six</li>
  <li>Seven</li>
  <li>Eight</li>
</ul>`
};

const customListStyleSpecs = {
  thai: {
    type: 'textual',
    counterStyleRenderer: thaiCounterStyle
  }
};

export default function App() {
  const { width } = useWindowDimensions();
  return (
    <RenderHtml
      contentWidth={width}
      source={source}
      customListStyleSpecs={customListStyleSpecs}
    />
  );
}

Press on the button below to show how this code renders on your device.

Creating a Counter Style#

@jsamr/counter-style allows you to create any counter style, translating strictly the @counter-style at-rule API defined in CSS Counter Styles Level 3 in a JavaScript API. In the below example, we are going to create an alphabetic counter style for the Russian alphabet:

Creating a List Style Type

JSX Source
HTML Snippet
TRT Snapshot

import React from 'react';
import { useWindowDimensions } from 'react-native';
import RenderHtml from 'react-native-render-html';
import CounterStyle from '@jsamr/counter-style';

const source = {
  html: `<ul style="list-style-type: lower-russian;">
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
  <li>Four</li>
  <li>Five</li>
  <li>Six</li>
  <li>Seven</li>
  <li>Eight</li>
</ul>`
};

const customListStyleSpecs = {
  'lower-russian': {
    type: 'textual',
    counterStyleRenderer: CounterStyle.alphabeticFromUnicodeRange(
      0x430, // а
      28     // number of chars in alphabet
    ).withSuffix(') ')
  }
};

export default function App() {
  const { width } = useWindowDimensions();
  return (
    <RenderHtml
      contentWidth={width}
      source={source}
      customListStyleSpecs={customListStyleSpecs}
    />
  );
}

Press on the button below to show how this code renders on your device.

Experimental RTL Mode#

Thanks to renderersProps prop, you can enable experimental RTL support for lists (see RenderersProps.ol and RenderersProps.ul).

note

For RTL mode to take effect, you need to have a dir attribute set for the list tag or one of its parents, or the direction style set for the list tag or one of its parents.

Example: Unordered Lists#

RTL Mode with Arabic Counter Style

JSX Source
HTML Snippet
TRT Snapshot

import React from 'react';
import { useWindowDimensions } from 'react-native';
import RenderHtml from 'react-native-render-html';

const source = {
  html: `<ul dir="rtl" style="list-style-type: disc;">
  <li>واحد</li>
  <li>اثنين</li>
  <li>ثلاثة</li>
  <li>أربعة</li>
  <li>خمسة</li>
  <li>ستة</li>
  <li>سبعة</li>
  <li>ثمانية</li>
</ul>`
};

const renderersProps = {
  ul: {
    enableExperimentalRtl: true
  }
};

export default function App() {
  const { width } = useWindowDimensions();
  return (
    <RenderHtml
      contentWidth={width}
      source={source}
      renderersProps={renderersProps}
    />
  );
}

Press on the button below to show how this code renders on your device.

Example: Ordered Lists Arabic#

RTL Mode with Arabic Counter Style

JSX Source
HTML Snippet
TRT Snapshot

import React from 'react';
import { useWindowDimensions } from 'react-native';
import RenderHtml from 'react-native-render-html';
import arabicIndic from '@jsamr/counter-style/presets/arabicIndic';

const source = {
  html: `<ol dir="rtl" style="list-style-type: arabic-indic;">
  <li>واحد</li>
  <li>اثنين</li>
  <li>ثلاثة</li>
  <li>أربعة</li>
  <li>خمسة</li>
  <li>ستة</li>
  <li>سبعة</li>
  <li>ثمانية</li>
</ol>`
};

const renderersProps = {
  ol: {
    enableExperimentalRtl: true
  }
};

const customListStyleSpecs = {
  'arabic-indic': {
    type: 'textual',
    counterStyleRenderer: arabicIndic
  }
};

export default function App() {
  const { width } = useWindowDimensions();
  return (
    <RenderHtml
      contentWidth={width}
      source={source}
      renderersProps={renderersProps}
      customListStyleSpecs={customListStyleSpecs}
    />
  );
}

Press on the button below to show how this code renders on your device.