Illustration

The @bento/illustration component allows you to render and manipulate SVG based illustrations while following the best practices for accessibility. The component is meant to wrap around your SVG content so it can introduce the required accessibility standards and provides a way to manipulate the SVG content using the provided properties.

Installation

npm install --save @bento/illustration

Props

The @bento/illustration exports the Illustration component. When rendering the component without any supplied properties, the component will automatically apply the following properties:

• focusable=false
• role=presentation

import { Illustration } from '@bento/illustration';

<Illustration>
  <YourSvg>
</Illustration>

The following properties are available to be used on the Illustration component:

| Prop | Type | Required | Description | |------|------|----------|------------| | slot | string | No | A named part of a component that can be customized. This is implemented by the consuming component. The exposed slot names of a component are available in the components documentation. | | title | string | No | Screen reader accessible title that explains the illustration. Introducing this property automatically changes the role attribute from presentation to img. | | children | ReactElement<SVGSVGElement, string \| JSXElementConstructor<any>> | Yes | The content to display. Should be an SVG. | | flip | "horizontal" \| "vertical" | No | Flip the illustration horizontally or vertically. | | rotate | 90 \| 180 \| 270 | No | Rotate the illustration by 90, 180, or 270 degrees. | | slots | Record<string, object \| Function> | No | An object that contains the customizations for the slots. The main way you interact with the slot system as a consumer. |

For all other properties specified on the Illustration component, the component will pass them down to the root SVG element of the component. Which would be the equivalent of you adding them directly to the child component.

Example

Accessibility

• title: The title attribute describes the illustration to screen readers.
• role: The role attribute is default set to presentation but is swapped to img when a title attribute is provided.

Customization

When using the flip or rotate properties, the component will apply the required transformations inside the SVG element by introducing a wrapping <g> element.

The transformations are not applied using CSS because they would affect the elements around the SVG content.

What's the difference between CSS transformations?

• If you rotate an SVG by 90 degrees in CSS, the SVG's bounding box remains the same. The 16x24 icon still takes space for 16x24, but it might overlap elements around it.
• If you rotate an SVG by 90 degrees in SVG Framework, the SVG's dimensions swap places. 16x24 icon becomes a 24x16 icon, and it does not affect the elements around it.

By applying the transformations to the SVG element by default, we've given you the option to choose how you want to apply the transformations. Use the props provided by the component to apply the transformations directly to the SVG element or introduce the className property to apply the transformations yourself using CSS, which is the recommended approach when you want to introduce animations to the component.

Slots

The component is created using our @bento/slots package and allows the assignment of the custom slot property to be used for overrides.

import { useProps } from '@bento/use-props';
import { Illustration } from '@bento/illustration';
import { withSlots } from '@bento/slots';

const MyCustomComponent = withSlots('MyCustomComponent', function Custom(args) {
  const { props } = useProps(args);

  return (
    <Illustration {...props} slot="illustration">
      <ContentsHere />
    </Illustration>
  )
});

See the @bento/slots package for more information on how to use the slot and slots properties.

Styling

Once you assign the className property to the component, you take full responsibility for the styling of the component, and it will remove any default styling that might be applied as part of this component.

import { Illustration } from '@bento/illustration';

<Illustration className="my-component">
  <YourSvg>
</Illustration>

The following data- attributes are introduced as part of the component render state:

• data-flip=horizontal|vertical: The component is flipped horizontally or vertically using the provided flip property.
• data-rotate=90|180|270: The component is rotated by the provided angle using the rotate property.

These data- attributes are introduced on the root element of the component and can be targeted using your previously provided custom className:

.my-component[data-flip] {
  /* The component is flipped */
}

.my-component[data-rotate] {
  /* The component is rotated */
}

To detect if the component has received a title attribute, you can use the following CSS selectors:

.my-component:has(title) {
  /* We have a <title> element as part of rendered result */
}
.my-component[role="img"] {
  /* The role is swapped to `img` from `presentation` when a title is provided */
}