Best Practices

Accessibility

Designing accessible products means they can be used effectively by as many people as possible, providing an inclusive experience for people with impairments and different needs.

Accessible design improves the product for everyone, as well as creating a better user experience for users with disabilities. In addition, most countries support accessibility with laws and regulations on both public and private sector organizations.

There is no single universal standard, so we recommend that you always check what policies are relevant for you. However, the W3C's Web Content Accessibility Guidelines 2.1 are most often referenced as an acceptable standard.

Compliance with Regulations

ReGraph is not a complete application by itself, it is a toolkit that you integrate into your own product. This means that accessibility should be considered at the level of the end product to give your application users the best user experience possible.

ReGraph as a visual medium is often exempt from compliance requirements because the functionality cannot always be fully reproduced in an accessible way. To help you with your accessibility audits, we have prepared a table that summarizes the guidelines of WCAG 2.1 and how they relate to ReGraph:

#wcagGuidelinesTable.docs-text-collapsable.hidden

We are always working on implementing features that make ReGraph more accessible and easier to use. Some tips using various ReGraph features are listed below.

Keyboard Controls

ReGraph doesn't have any native keyboard navigation behavior, which means that you can customize keyboard controls without having to override any default actions. To help you do this, ReGraph offers a number of native chart events and time bar events that you can respond to. It also supports standard element events such as keydown, focus and others.

This example shows how to customize keyboard navigation behavior by calling the pan() and zoom() instance methods in a handler triggered by a keydown event listener:

ReGraph Example

Log in to view live examples

If you want more control over the exact way the chart view changes on a key press, you can update the view prop to change the view of the chart instead.

Some browsers support some keyboard navigation by default, e.g. using the Tab key to iterate through form controls. When planning keyboard shortcuts, you should avoid overriding native browser and operating system shortcuts that affect the browser behavior.

Accessible Styling

ReGraph Example

Log in to view live examples

Text

We recommend using simple sans-serif fonts as they are generally easier to read for most users. Alongside text, you should also convey the meaning in another way that doesn't require reading or understanding the language, such as font icons, glyphs or images.

Color

The colors you use should always have a sufficient contrast ratio. Online tools such as this WebAIM Contrast checker can help you check your color combinations for accessibility. When styling nodes, you can also consider using SVG images with patterns and textures instead of colors.

Show meaning in multiple ways

You should not rely on a single method, such as color, to convey a meaning. On nodes you can also use node styling to add labels, images, font icons or glyphs, while on links you can use text-based labels, glyphs, dashed and dotted line styles or flow animation.

Separate and foreground content

To make charts as readable as possible, choose the layout that best represents the type of your data and connections. Consider what is the best tightness for your chart. To reduce the cognitive load, consider foregrounding and backgrounding relevant or selected items. See more in the Neighbors example.

ARIA Support

ARIA (Accessible Rich Internet Applications), is a set of roles and attributes that can supplement HTML elements or attributes that don't have built-in accessible semantics or behavior.

ReGraph lets you set ARIA properties on the DOM element. The Playground lists all supported ARIA props in the code-autocomplete when you start typing.

Note that there is no programmatic access to nodes/links rendered on the canvas. You can use aria-hidden property to hide it from screen readers.

<div
  style={{ height: '100%' }}
  aria-label={ `A simple chart` }
  aria-description=
  { `A simple chart with ${Object.keys(items).length} green node(s)` }
>
<Chart aria-hidden={true} items={{ node1: { color: '#2dcda8' } }} />
</div>

Charts and Audio

Seeing a chart is essential for spotting and understanding the patterns and connections revealed in the data, which makes it challenging to make charts accessible e.g. for screen readers. As an alternative, you can hide the chart's div from screen readers using the aria-hidden property, and instead supply a text in the aria-description that summarizes the chart to the extent needed in your context, for example:

The element here is a chart made of nodes and links, where nodes represent employees from several departments and links represent their email communications. The chart communicates that most emails are sent between management and marketing.

You can also use audio as an additional channel to written information or as an extra method of alerting or highlighting, but remember to never rely on audio alone.

ReGraph Example

Log in to view live examples

Testing Tips

When building ReGraph into your applications, you may be interested in automated integration testing. ReGraph has a number of helpful APIs available to give you information about the items in the chart.

Chart events

The onUpdateComplete event is invoked each time the chart has finished updating. Use this event e.g. to check when the chart animation is complete. This event is also suitable for production.

Chart instance methods

The following functions, currently all in beta, are particularly useful for use in integration tests. To use them, give access to the chart by exposing your chart's ref on the window:

const MyFunctionalComponent = (props) => {
  const { items } = props;

  const chartRef = React.useRef(null);

  // expose the ref on the top-most window
  window.top.chart = chartRef

  return (
    <Chart
      ref={chartRef}
      items={items}
    />
  );
};

Then you can use them in your tests:

const item = window.chart.current.getItemInfo('node1');

See also Instance Methods for more information.

getItemAtViewCoordinates

The getItemAtViewCoordinates instance method returns an object with information about the item or sub-item at the specified view coordinates.

getItemInfo

The getItemInfo instance method returns a list of all chart items, or details of a specified item if a valid id is passed.

getViewCoordinatesOfItem

The getViewCoordinatesOfItem instance method returns an object with view coordinates of the specified item or sub-item.

Troubleshooting

We offer guidance on common problems installing and running ReGraph. If this doesn't solve your issue, contact support.

yarn/npm hangs while installing ReGraph

Make sure you're using an up-to-date package manager.

We've seen issues when installing with older versions of yarn - we recommend using version 1.13 or greater.

The chart is too small

The ReGraph chart will try to size itself to fill its containing element.

You can use CSS properties to set the container's size, just like with any DOM element. Common sizing strategies include using:

• a fixed or percentage height,
• a flex container (display: flex on the parent element),
• absolute positioning (position: absolute).

State updates not synchronized

If you're having trouble with synchronizing state updates, try running in production mode.

Errors when rendering ReGraph with next.js

ReGraph can only run in a web browser because it requires the DOM and other Web APIs to render correctly.

If you are using ReGraph with next.js, you need to make sure that ReGraph components are not rendered on the server side.

See the next.js documentation on how to disable SSR.

SVG icons fail to load in some browsers

If some browsers fail to load your SVG icons while others work correctly, it's likely a browser issue. One of the causes might be the size of the SVG file. To improve cross-browser compatibility, set the width and height attributes in your SVG files or optimize the size of your SVG using an optimizer such as SVGO.