itwin/itwinui

A design system for building beautiful and well-working web interfaces.

An open-source design system that helps us build a unified web experience.

iTwinUI is a design system for building beautiful and well working web UI components within Bentley Systems & iTwin.js applications. It supports light and dark color schemes and also comes with high contrast versions of both.

iTwinUI consists of the following packages:

• @itwin/itwinui-css - the CSS for every component as well as some global styles
• @itwin/itwinui-variables - CSS variables for iTwinUI's design tokens
• @itwin/itwinui-react - react components that consume @itwin/itwinui-css

---

🆕 iTwinUI v3 is now available! To upgrade from an older version, check out the v3 migration guide.

---

Usage

The easiest way to get started with iTwinUI is by using React components from @itwin/itwinui-react:

import { ThemeProvider, Button } from '@itwin/itwinui-react';
import '@itwin/itwinui-react/styles.css';

export default function App() {
  return (
    <>
      <ThemeProvider theme='light'>
        <Button>Hello!</Button>
      </ThemeProvider>
    </>
  );
}

For more details, check out the iTwinUI documentation website.

---

Contributing

Are you interested in helping iTwinUI grow and expand? You can submit feature requests or bugs by creating issues. Please read our CONTRIBUTING.md for more information.

itwinui's Issues

Table: header cell always has cursor pointer

Environment

• Package version(s): 0.20.0

Header cell always has cursor: pointer but the column might not always be actionable/sortable.
Need to have separate class for this.

Active menu-item doesn't show outline when overflow is set

Select looks like this after 0.24.0:

This is happening because we need to set overflow-y: auto on menu (to make it scroll when there are too many items).

I think we might need to revert outline back to border or box-shadow. Or figure something out with negative margins and insets.

Originally posted by @mayank99 in iTwin/iTwinUI-react#203 (comment)

Add iPhone notch support

Add responsiveness to Header and HeaderButton

Feature

Improve header width management so it does not allow extending beyond the page, also, make the HeaderButton handle constrained spaces by adding Ellipsis, right now it forces to display everything all the time, and given that the content of those button will be filled with user inputs, it might not always have a useful size:

Examples

Something along these lines:

Add CSS fallback handling of broken UserIcon images

Feature

Add CSS handling of broken user-icon images with syled and colored user abbreviations.

Description with possible css solution in iTwin/iTwinUI-react#98.

Examples

Something like below did work, however the background color is always present so the image MUST be covering the background, not sure how else we could pass on the img::after { background-color: UserColor}

img {
  font-family: "Helvetica";
  font-weight: 300;
  line-height: 1px;
  text-align: center;
  font-size: 1px;

  width: 24px;
  height: 24px;
  display: block;
  position: relative;
  border-radius: 50%;
}

img:empty {
  padding: 5px;
}

img::before {
  line-height: 32px;
  font-size: 16px;
  content: attr(alt);
  display: block;
  position: absolute;
  left: 0;
  top: 0;
  width: 100%;
  height: 100%;
  margin: 0;
  font-style: normal;
  font-weight: 600;
  border-radius: 50%;

  text-align: center;
  text-decoration: none;
  text-transform: uppercase;
  background-color: inherit;
  color: var(--iui-color-foreground-accessory);
}

Cleanup user icon component

• Class name refactor.
• Remove z-index.
• When image is not an ideal square then it loses aspect ratio.

Tooltip bugs: blurring and shadow

After adding the frosted glass effect in #19, three different visual bugs show up:

1. Tooltip text is blurry if using CSS transforms (workaround in iTwin/iTwinUI-react#25)
2. Tooltip target element is also blurry on hover (when tooltip shows) similar to #44
3. There is a very noticeable shadow covering the target element

All 3 are noticeable in this gif:

Environment info: Windows 10, Chrome 89, [email protected], [email protected]

Allow overriding Slider styles

iTwin.js team needs the ability to use an SVG either for the slider thumb or inside of the slider thumb. Screenshot of one of the reasons for it below:

Table is missing active filter class and example with it

What color fill should be for SVG?

Menu: adding seperator between the list items

Environment

• Package version(s):0.13.1

In itwin.bentley.con or plansight , a typical header dropdown has seperator(s) in the menu:

I couldn't find any styling for it in ITwinUI.

Badge color system could use a rework

Documenting 3 issues with current badges:

1. There is no default color applied when doing this:

<span class="iui-badge">Label</span>

2. There is no proper styling for status colors (e.g. success, failure, etc)

3. Most of the current data-viz colors (recommended for badge) are inaccessible due to low contrast.

Reducing specificity of button selectors

Currently, the long button selectors make it really hard to add custom styles.

Some requirements:

• button icon should have a specificity of 0-1-0 (by adding a flat level class).
• there should be a modifier for the default button (e.g. .iui-button.iui-default) so we can reference it directly without :not(.iui-cta):not(.iui-borderless):not(.iui-high-visibility).
• hover and focus states should have lower specificity across the board, to allow easier overrides for component-specific use cases (e.g. in split header button) as well as user's custom use cases (e.g. different hover color).

ProgressRadial: Need additional sizes

Feature:
The iModel.js UI team is now consuming iTwinUI and is deprecating its own Spinner & ProgressSpinner components in favor of the ProgressRadial component in iTwinUI-react. The iModel.js spinner components support 16px, 32px and 64px sizes. The ProgressRadial supports two sizes: small (24px) and unspecified (32px). We are asking for support of all sizes (16px, 24px, 32px and 64px) in the ProgressRadial component.

Examples:
<ProgressRadial size="tiny" />
<ProgressRadial size="small" />
<ProgressRadial size="medium" /> is same as <ProgressRadial />
<ProgressRadial size="large" />

Slider component

Wizard: alignment issues when resizing

Environment

• Package version(s): 1.4.0
• Operating System: Microsoft Windows 10 Enterprise
• Browser name and version: Mozilla Firefox 88.0.1 (64-bit)

Code Sandbox

Link to a minimal repro (fork this code sandbox): https://codesandbox.io/s/itwinui-react-example-forked-lkx80?file=/src/App.tsx

Steps to reproduce

1. Use 5 wizard steps with varying text length.
2. Shrink browser window until step circles get detached
   

Actual behavior

Wizard step circles are detached from tracks, text is left aligned.

Expected behavior

Wizard circles do not get detached, text is center aligned.

Additional information

It may be argued that we should use long wizard for that specific case and I am currently considering that. However, I still think wizard should be able to shrink more than it currently does. I think the solution is rather simple for that:

• Add css rule justify-content: flex-end for .iui-wizards-step selector
• Add css rule text-align: center for .iui-wizards-step-title selector

Result:

I can contribute to this issue, if it gets approved.

Menu: multiline list items

Environment

• Package version(s): 0.13.1

If you look at Itwin.bentley.com or plansight the typical header dropdown has multiline list items:

I tried adding multiple divs inside the but it shows only the first

:

<ul class="iui-menu">
          @if (_items != null)
          {
              foreach (var item in _items)
              {
                  <li @onclick="() => ItemClicked(item)">
                      <span class="iui-content">
                          **<div >
                              @item.ItemName
                          </div>
                          <div>
                              @item.ItemDescription
                          </div>**
                      </span>
                  </li>

Icons variables are not exported to users

Review icons code, cleanup and export useful variables to the users through our style variables.

Compile error introduced with 0.19.0

Environment

• "@itwin/itwinui-css": "^0.19.0",
• Windows 10
• Chrome 91.0.4472.77

Steps to reproduce

Upgrade to itwinui-css 0.19.0

Actual behavior

Getting build error:

Error: Undefined variable.
    ╷
    │ $iui-component-padding-horizontal: $iui-sm; // 12px
    │                                    ^^^^^^^
    ╵

Expected behavior

No build errors.

Add vertical tabs modifier

Feature

Add a modifier class to .iui-tabs enabling vertical tab layout.

Examples

Example above is missing the blue stripe.

Sidenav buttons style is overriden by button

Steps to reproduce

Seems to be depending on the order of css files imports, no easy reproduction steps.

Expected behavior

Borders on hover are not this much dark @FlyersPh9

Additional information

Button style overrride sidenav button styles:

ExpandableBlock: animation should be updated

We got an issue in React iTwin/iTwinUI-react#243 that Select is "jumping" in ExpandableBlock.
It is caused by having transform: scaleY(...). Need to remove it and just make the same animation as Table has for expandable row.

FileUploadTemplate: input should be inside label

Follow up to iTwin/iTwinUI-react#123 (comment). File input should not need id to work with label.

The solution is to just use implicit association:

<label><input type="file" /></label>

But the > in front of .iui-browse-input prevents that.

iTwinUI/src/file-upload/file-upload.scss

Line 34 in 1941463

> .iui-browse-input {

Review inline and default inputs for icon and label placement

The input label, status icon, and status message should be independent of each other and should not always be influenced by default/inline variants, for greater flexibility.

Improving the "status icon" logic will also allow:

• Custom components to be placed at the end of input (e.g.: #93 and #53)
• Tooltips on icons

Column filter component

Feature

The user clicks on the filter icon within a table column header & a dropdown menu appears with options.

Examples

Blurry text issues in tooltip and tile

Tile:

After merging #37 (workaround for #44 ), the tile text always stays slightly blurry, instead of only becoming blurred for the transition period.

---

Tooltip:

After adding the frosted glass effect in #19, 2 different visual bugs show up. See #43 for additional context

• Tooltip text is blurry if using CSS transforms
  • Workaround: iTwin/iTwinUI-react#25
• Tooltip target element is also blurry on hover (when tooltip shows)

For now, the frosted glass effect has been removed (in #48) until this is solved.

Update: It seems that the current "translucent" effect is causing readability issues in light theme.
See iTwin/iTwinUI-react#142

---

Environment info: Windows 10, Chrome 89, [email protected], [email protected]. macOS does not appear to have this issue.

Select not showing ellipsis when value is very long and select is small.

Environment

• Package version(s): Branch Table Refactor
• Operating System: Windows 10
• Browser name and version: chrome latest

Steps to reproduce

If text in Select is long and the size of Select cannot be as long due to limited space. The box will not overflow and text will not ellipsis.

Actual behavior

• Modifying the backstop with width smaller than the text inside.
  • 
• With extreme reduce size
  • 
• Compare with iui-input with the same limited space :
  • 

Expected behavior

• Ellipsis appear in the selected field.
• Box overflow is hidden which is not and is pushing right sibling outside of the designate zone.
• ::After element is hidding text so it don't appear under the ▲/▼

Additional

Try testing iui-input beside iui-select with the same restricted space, if iui-input is smaller than iui-select, there is a problems.

Add InputDatePicker component as a controlled DatePicking Input field.

Feature

So DatePicker is allowing user to pick a date. Though, DatePicker is the whole component when I would expect DatePicker to be a floating component attach to something else. I would expect a DatePicker to be an input field where when click on it, show up a floating component that help choosing a date. I wasn't expecting that DatePicker would be the body of the floating component.

It can make sense to keep the DatePicker like this for custom/advance feature, but I think 95% of the case, people will need an Input like component with the DatePicker built-in. So I'm requesting an new component called InputDatePicker which handle date picking in a form.

Examples

<PanelProperty 
  editMode={true} 
  editInput={ <DatePicker date={editedObject.Date} onChange={(value) => setObject({...editedObject, Date: value,})} /> }
/>

That's what I would be expecting from a DatePicker :

That what I got :

iui-body should default to background-2

Discussed in #103 (and continuation of #33 (comment))

^{Originally posted by mayank99 May 20, 2021}

For some reason, we are using background-1 in .iui-body, not background-2.

iTwinUI/src/style/global.scss

Lines 5 to 7 in a9fc7b6

	.iui-body {
	@include themed {
	background-color: t(iui-color-background-1);

Currently, when header and sidenav are placed above background-1, they just look bad/wrong and there isn't enough contrast. So the user would have to know all this context and need to manually override with background-2 (and that's asking too much from the user).

Stack multiple user icons

Add support for custom content in menu item (non-interactive)

Similar to the column filter menus that we offer, we should offer a standard user profile menu accessed from the header.

Tile content is hidden when it is used as ExpandableBlock child

Environment

• Package version(s): 1.4.1
• Operating System: Windows 10
• Browser name and version: Opera 76.0.4017.154

Code Sandbox

Link to a minimal repro (fork this code sandbox): https://codesandbox.io/s/itwinui-react-example-forked-09ru0?file=/src/App.tsx

Steps to reproduce

1. Add Tile as ExpandableBlock child component
2. Expand Block

Actual behavior

Tile name, description, metadata, options & etc. are not visible.

Expected behavior

All Tile component content is visible if defined.

Additional information

Locally managed to workaround this issue by unsetting following styles:

  .iui-expanded {
    .iui-content {
      transform: unset !important;
      height: unset;
      opacity: unset;
    }
  }

Fix clipped focus styling

The focus styling can appear cut off on elements that are side by side (grouped buttons, tabs). Proposed solution is to use an inset outline rather than box shadow.

Make colons (:) on input fields optional

Feature

Currently colons get automatically appended to labels of inputs. This seems to clash with certain UX standards and can make it look awkwardly when using a required marker.

Examples

Of course it can be overridden via css, but that seems like going against the grain. Perhaps it would be better if the colon would be optional addition, or left for consumers to manually add them when needed?

Margin Prop for Typography Components

Feature

At the moment to strip the bottom margin from typography you have to override it using css, I think it would be nice to have a prop for typography components that determines if margin is applied to the text.

Examples

A Boolean prop like:
<Header useMargin={true/false} />
or maybe a prop to set your own margin value:
<Header marginSize={value} />

Automating boilerplate for adding new components

Need a script that adds all the boilerplate required for new component files. Should take care of adding barrel imports, etc

Similar to https://github.com/iTwin/iTwinUI-react/blob/main/scripts/createComponent.js

Active tab have different behaviors for fill and color

Environment

• Package version(s): css 0.16.0, react 1.5.0
• Operating System: Windows
• Browser name and version: Chrome, rather up to date.

Code Sandbox

Link to a minimal repro (fork this code sandbox):

Steps to reproduce

React:

      <HorizontalTabs
        labels={[
          <span className={"tab-with-icon"} key="favorite">
            <SvgStarHollow />
            <p>Favorite projects</p>
          </span>,
          <span className={"tab-with-icon"} key={"recents"}>
            <SvgCalendar />
            <p>Recent projects</p>
          </span>,
          <span className={"tab-with-icon"} key={"all"}>
            <SvgList />
            <p>My projects</p>
          </span>,
        ]}
        onTabSelected={()=> alert("SELECTED");}
        activeIndex={0}
        type={"borderless"}
      >

CSS:

.tab-with-icon {
  display: flex;
  flex-direction: row;
  align-items: center;
  gap: 11px;

  svg {
    height: 16px;
    width: 16px;
    //fill: currentColor; <-- Uncommenting this for a workaround.
  }
}

Actual behavior

The fill color is changing depending on hover state when tab is active, however the text color is not.

Expected behavior

I expected the icon to have the same color behavior than the text, hence the workaround of "currentColor".

As the color change is occuring without me adding anything, I did not expect to need to add something to "complete" the behavior.

Additional information

Here is a visual of what is happening, the fill is simply not overriden at the same place/conditions than the color is, so maybe the default behavior should simply be to apply fill: currentColor to the SVG instead of changing fill on top of color.

Badge remove transform text uppercase automatically.

iTwinUI/src/badge/badge.scss

Line 13 in c68f250

text-transform: uppercase;

Text should not have a force uppercase transformation. Should be decide within the code, not by the CSS.

UserIcon in IconButton is not properly sized in some scenario.

Environment

• Package version(s): 0.16.0

Google Chrome	90.0.4430.212 (Official Build) (64-bit) (cohort: Stable)
Revision	e3cd97fc771b893b7fd1879196d1215b622c2bed-refs/branch-heads/4430@{#1429}
OS	Windows 10 OS Version 1909 (Build 18363.1556)

Code Sandbox

Could not create a repo as this issue is not occuring in there, not sure how to control that.

Steps to reproduce

<IconButton styleType={"borderless"}>
  <UserIcon
    size={"medium"}
    abbreviation={"IU"}
    backgroundColor={getUserColor("IU")}
  />
</IconButton>

Actual behavior

UserIcon with size "medium" is overriden by default ".iui-button>.iui-icon" in some scenario (which I could not reproduce in code sandbox) when the build output changes the css order...

This is what I get in my application:

This is what I get in Storybook or Codesandbox examples:

Expected behavior

I expect the UserIcon to have the specified size even if I put it in a IconButton, so I guess the .iui-user-icon.iui-user-icon should be made even more specific so order does not impact the output.

Additional information

The specificity of the 2 height/width classes are the same (2 classes), so it boils down to the order in which the classes are loaded in the browser. I dont know why my build is putting the .iui-user-icon.iui-user-icon before the .iui-button>.iui-icon, but it does...
I'm using a package that uses iTwinui-react components and @bentley/react-scripts, I cant test that in codesandbox as those packages are not publicly available at the moment.

In my test, I was also inside a Header (not set to slim mode), but that didnt seem to add anything regarding the classes.
Not that when in slim mode, the usericon actually get to the correct 24px size, instead of the 16px size of iui-icon.

(I must admit that I initially expected the size to be handled by the header in non slim mode too, but it went to the default small size.)

Contributing guide needs instructions for fork workflow

Tile hover state causes blurry text

This issue originates from #37 (which is a workaround for it, not a proper fix).

Basically, it amounts to a browser bug where using a scale or translateZ CSS transform leads to blurry text.
Environment info: Windows 10, Chrome 89, [email protected], [email protected]

Ultimately, we might have to rethink the hover state for tile because it makes things worse more than it helps us: in addition to this text blurring, there is also some image blurring, not to mention the unintuitive UX for options menu (and also the metadata size bug partially fixed in #18).

If we could just avoid using a scale transform on the image, and instead have a simpler hover state, it might fix all of those issues.

Header component

Breadcrumb component

Overlay loading state container

• Set the standard of when to use vs not
• Provide css for overlay loading element both: whole viewport and per container

Side navigation

Feature

A side navigation component provided by iTwinUI (and iTwinUI-react) would be really useful given the number of interactions and animation such a component potentially have.

• Menu state: Colapsed (with tooltip), Expanded right, Expanded below. (Last one is used when intended for mobile)
• Menu opening behavior: Push content, Overlay.
• Menu Item distribution: Allow top and bottom items.
• Menu Item states: Normal, Active, Hover, Disabled.
• Menu Item behaviors: Link, Sub-Menu, Content panel.

Examples

https://itwin.bentley.com
https://construction.bentley.com
https://plantsight.bentley.com
https://projectwise365.bentley.com

LabeledTextArea/Input : Having icon inside input while displayStyle is default

Feature

Taking my previous Feature Request iTwin/iTwinUI-react#137 I would like to have a TextArea with the label at the top of the TextArea but the icon inside of the textarea so I can use this solution : iTwin/iTwinUI-react#137 (comment) this way :

ButtonToolbar component or add support for input and select in ButtonGroup

Feature

So I would like to have an Input or a Select beside a button or any horizontal component that could be interact with. Right now the closest things to that is the ButtonGroup, but it's Button exclusive... I would like it to be for anything that can be interact with. In my case, Select and Input handling in ButtonGroup is what I'm looking for.

With Input type="datetime_local", there is a button already include in the input, but I need it to be able to erase it which isn't possible with native browser datetime input. So I'm adding a button to the right, but I would like to have preset style so I don't have to write the style.

Examples

Something like this :

Right now adding Input in ButtonGroup look like this :

Thinner iui-input version

Feature

So at the moment, iui-input has only one possible size which is kinda big. I would like to being able to use a thin version of input so my layout is not affected vertically when I switch between Read mode and Edit mode in an InfoPanel.

Examples

Showing the wrong result here :

Review and update Table classes and html structure

Add head content for better social sharing

Follow this guide: https://www.matuzo.at/blog/html-boilerplate/

Fix DEPRECATION WARNING when using with Dart Sass

Environment

• Package version(s): 0.17.1
• Operating System: Windows 10
• Browser name and version: NA - warnings during build

Code Sandbox

None

Steps to reproduce

1. use scss files in product that uses dart Sass - sass: ^1.32.0 (such as iModeljs)

Actual behavior

DEPRECATION WARNING: Using / for division is deprecated and will be removed in Dart Sass 2.0.0.
More info and automated migrator: https://sass-lang.com/d/slash-div
   ╷
856 │ $iui-inputs-padding: (($iui-inputs-height - $iui-line-height) / 2) - 1;
    │                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expected behavior

No warning

Additional information

Easy fix - convert / 2 -> * 0.5