README
<bliss-avatar>
<bliss-avatar>
is a representation of a user account or user group (i.e. Human Resources
). It displays either the initials of an entry or number and is purely text-based (no images or other assets).
In previous versions of Bliss CSS, this component was named User Circle
.
📦 Installation
To install this component, run:
yarn add @bliss-design-system/avatar
🏎 Usage
To use this component, you'll need to register the component to the window
's Custom Elements Registry. In order to achieve that, you'll want to call this function within your application's client-facing entry file:
import { blissRegisterAvatar } from '@bliss-design-system/avatar';
blissRegisterAvatar(); // Registers <bliss-avatar>
That will make the component available in your application and you can use it like this:
<!-- Render an avatar with the default user variant displaying MM -->
<bliss-avatar content="Max Mustermann"></bliss-avatar>
You can also pass a number as the content
value to automatically apply the more
variant:
<!-- Render an avatar with the more variant displaying +3 -->
<bliss-avatar content="3"></bliss-avatar>
Properties
The component accepts the following properties:
Property | Type | Description | Default | Required | Options |
---|---|---|---|---|---|
content | String | Determines what is displayed in the avatar | "" |
true | - |
variant | String | Applies a variant to the avatar component | user |
false | user , user-group , more |
compact | Boolean | Adds a border to the avatar without increasing the size | false |
false | - |
hasTooltip | Boolean | Removes the title attribute content when set to true |
false |
false | - |
Known limitations
The avatar generates the displayed initials based on the text provided through the content
attribute. It will do this by grabbing the first letter character from the first word and last word (if applicable). If one word is provided, only the first letter from that word will be displayed (i.e. a user group called Finance
will display F
).
The avatar will pass over and not show any numbers within the provided content (i.e. a user group called Human Resources 101
will display HR
). If a number is included within a word, then it will display the first character regardless of if it's a number or letter (i.e. 2021Karen
will display 2
and Karen2021
will display K
).
If the value provided through the content
attribute is a number, then the more
variant will automatically be applied. This means that the avatar will display the provided number preceded by a +
character (i.e. 8
will display +8
).
🫕 Contributing
If you'd like to contribute, please open an issue with your suggested change on our Proposal Board. Once that is accepted, either the Bliss team will work on it or you can make changes locally by doing the following:
# Clone this repository
git clone https://gitlab.com/bliss-design-system/components.git
# Move into the component toolkit
cd components/
# Install the dependencies
yarn
You don't need to move into the package's directory to run storybook, tests or anything else. All of those commands exist in the root of the component toolkit, so while you can work on the component within its specific folder, you don't need to move through directories to run anything.
Demoing with Storybook
You can see all of your changes as you make them on Storybook.
To run a local instance of Storybook for this component, run:
yarn storybook
Testing
If you want to test as you develop, run:
yarn test
// or
yarn test:watch
Committing
We follow the Conventional Commits specification, meaning that you'll be prompted to fill out a descriptive message when you commit. We also use these commits to manage our releases, so we appreciate details.
As a guideline for this component, we use:
fix
for bug fixes, minor stylistic improvements, etc.feat
for any backward compatible API changes.
For anything that breaks backwards compatibility or introduces significant changes that require a major version change, please get in touch with the team.
Opening a merge request
When you're ready to open a merge request, please use a descriptive title and fill out the provided template.
The team will be notified, but it helps to post your merge request in #bliss_support.
🙃 Troubleshooting
We'll fill this section out as we go and as issues are raised. But if you haven't found what you're looking for, get in touch via bliss@bryter.io or via the #bliss_support Slack channel ✨.