Element: <oj-avatar>

Oracle® JavaScript Extension Toolkit (JET)
16.1.0
F92237-01

Since:
  • 4.0.0
Module:
  • ojavatar

Note: This component is in maintenance mode. Suggested alternative: <oj-c-avatar>. For help updating an existing application, see the migration section.

QuickNav

Attributes

Methods

Other Topics


JET Avatar

Description: Themeable, WAI-ARIA-compliant element that often represents a person.

A JET avatar is an icon capable of displaying a custom image, or initials, or a placeholder image. The order of precedence for what is displayed, in order from highest to lowest, is:

  1. Custom image specified through the "src" attribute
  2. Initials specified through the "initials" attribute
  3. Default placeholder image
//Avatar with initials
<oj-avatar initials="AB">
</oj-avatar>

Accessibility

To make the component accessible, the application must set the role attribute of oj-avatar to 'img' and provide a value for the aria-label attribute. Note that the component only needs to be made accessible if any associated information (e.g. the name of the person represented by the oj-avatar) is not already available to assistive technologies (e.g. by rendering the name in addition to the avatar as part of the page content).

JET Avatar does not have any interaction with the application, therefore it is not keyboard navigable by default. The aria-label will be picked up by the tabbable/focusable parent unless it is overriden by the application. The application can set a tooltip by setting the title attribute of the avatar. It is recommended that the title and aria-label attributes are in sync.

In order to meet accessibility requirements for text, color contrast ratio between the background color and text must be greater than 4.5 for the two smallest avatars and 3.1 for the five larger avatars. Avatar's default background satisfies the 4.5 color contrast ratio. If colors are customized through theming, the application is responsible for specifying colors that satisfy the contrast ratio requirements.

Image

The avatar will display the image provided from the src attribute if the src attribute is populated. If the src attribute is not provided and the initials have been, the initials will be displayed. If neither src nor initials attributes are populated, a single person placeholder image is shown. Use the class oj-avatar-group-image to use the group placeholder image. Examples displaying each type of avatar: 

//Individual Placeholder
<oj-avatar>
 </oj-avatar>
//Group Placeholder
<oj-avatar class="oj-avatar-group-image">
 </oj-avatar>
//Initials
<oj-avatar initials="AB">
</oj-avatar>
//Image
<oj-avatar initials="AB" src="image.jpg">
</oj-avatar>

Migration

Read about current Core Pack limitations to decide when to migrate.
Please make note of the following:

  • Deprecated APIs are not available in Core Pack, and are not documented in this migration section.
  • Before trying to migrate to Core Pack run the JET audits and fix any issues before proceeding.
  • The refresh() method is no longer supported in Core Pack. See the Core Pack Migration Guide for more information.

To migrate from oj-avatar to oj-c-avatar, you need to revise the import statement and references to oj-avatar in your app. Please note the changes between the two components below.
Size attribute

The enum values for the size attribute have changed from 'xxs' and 'xxl' to '2xs', and '2xl'.

Role attribute

If aria-label is set on the component, the role attribute will be set internally. The application should no longer populate the role attribute.


Usage

Signature:

interface AvatarElement

Typescript Import Format
//To typecheck the element APIs, import as below.
import { AvatarElement } from "ojs/ojavatar";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojavatar";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Styling Classes

.oj-avatar-group-image
Use to display avatar group placeholder image instead of single person placeholder image.
Deprecated:
Since Description
12.1.0 'oj-avatar-group-image' class has been deprecated. The group placeholder icon can still be shown by setting the icon-class attribute to 'oj-ux-ico-contact-group'.
Example
//Group Placeholder
 <oj-avatar class="oj-avatar-group-image">
 </oj-avatar>

CSS Variables

See JET CSS Variables for additional details.
Avatar Color CSS
CSS variables that specify Avatar colors
Name Type Description
--oj-avatar-bg-color <color> Avatar background color
--oj-avatar-text-color <color> Avatar text color
Avatar Sizing and Display CSS
CSS variables that specify Avatar sizing and display characteristics
Name Type Description
--oj-avatar-pattern-display block | none Avatar pattern display behavior. This is only supported in Redwood.
--oj-avatar-size <length> Avatar size
--oj-avatar-border-radius <length> | <percentage> Avatar border radius, only applied to the square avatar
Avatar Font CSS
CSS variables that specify Avatar font characteristics
Name Type Description
--oj-avatar-initials-font-size <length> Avatar font size for initials
--oj-avatar-initials-font-weight <font_weight> Avatar font weight for initials

Attributes

background :"neutral"|"orange"|"green"|"teal"|"blue"|"slate"|"mauve"|"pink"|"purple"|"lilac"|"gray"|"red"|"forest" background :"neutral"|"orange"|"green"|"teal"|"blue"|"slate"|"pink"|"purple"|"lilac"|"gray"

Specifies the background of the avatar.
Supported Values:
Value Description
neutral Neutral background (default, if unspecified)
orange Orange background
green Green background
teal Teal background
blue Blue background
slate Slate background
mauve Mauve background
Deprecated:
Since Description
10.0.0 This value will be removed in the future. Please use other colors.
pink Pink background
purple Purple background
lilac Lilac background
gray Gray background
red Red background
Deprecated:
Since Description
10.0.0 This value will be removed in the future. Please use other colors.
forest Forest background
Deprecated:
Since Description
10.0.0 This value will be removed in the future. Please use other colors.
Default Value:
  • 'neutral'
Names
Item Name
Property background
Property change event backgroundChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-background-changed

icon-class :string

Specifies the icon class to be displayed. If populated, src and initials will be ignored.
Default Value:
  • ''
Names
Item Name
Property iconClass
Property change event iconClassChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-icon-class-changed

initials :string|null

Specifies the initials of the avatar. Will only be displayed if the src and iconClass attributes are null. IntlConverterUtils.getInitials can be used to generate initials from first and last names in a locale-specific manner.
Default Value:
  • null
Names
Item Name
Property initials
Property change event initialsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-initials-changed

shape :"square"|"circle"

Specifies the shape of the avatar. Can be square or circle.The default value of this property varies by theme.
Supported Values:
Value Description
square square avatar (default, if unspecified)
circle circular avatar
Names
Item Name
Property shape
Property change event shapeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-shape-changed

size :"2xs"|"xxs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"xxl" size :"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"

Specifies the size of the avatar.
Supported Values:
Value Description
2xs extra, extra small avatar
xxs extra, extra small avatar(deprecated)
Deprecated:
Since Description
13.0.0 These values will be removed in the future. Please use '2xl' or '2xs' instead.
xs extra small avatar
sm small avatar
md medium avatar (default, if unspecified)
lg large avatar
xl extra large avatar
2xl extra, extra large avatar
xxl extra, extra large avatar(deprecated)
Deprecated:
Since Description
13.0.0 These values will be removed in the future. Please use '2xl' or '2xs' instead.
Default Value:
  • 'md'
Names
Item Name
Property size
Property change event sizeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-size-changed

src :string|null

Specifies the src for the image of the avatar. Image will be rendered as a background image. Will be ignored if iconClass is populated.
Default Value:
  • null
Names
Item Name
Property src
Property change event srcChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-src-changed

Methods

getProperty(property) : {any}

Retrieves a value for a property or a single subproperty for complex properties.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Returns:
Type
void