FieldBase

This component contains all the common behaviour and styles for fields

FieldBase provides an Atlassian Design Guidelines compatible implementation for:

• Labels: spacing, margins, accessibility.
• Fields: sizing, borders, colors, wrapping behaviour, hover/focus states.
• Validation: styles (built in validation coming soon!)

FieldBase's will work by themselves but are really meant to be extended into a full field component.

Try it out

Interact with a live demo of the ak-field-base component.

Installation

npm install ak-field-base

Using the component

The typical use-case for an ak-field-base is to create a new component. It makes no assumptions about libraries or tools and can be extended however you like (React, Skatejs, Vanilla JS, etc).

Usually you will want some form of input for the extended component. You can add that to fieldBase using the input-slot slot like so:

<ak-field-base label="A slotted input">
  <input slot="input-slot" type="text" value="I am slotted in a field-base!" />
</ak-field-base>

Note: React consumers will need to use the is prop to tell React to treat the input as a Custom Element, otherwise it will not recognise the slot attribute.

<ak-field-base label="A slotted input">
 <input is slot="input-slot" type="text" defaultValue="I am slotted in a field-base!" />
</ak-field-base>

You'll also want to style the input to make it blend in with the fieldBase.

Styling Content

You'll typically want to apply some styles to any input fields/text areas you use inside a field-base.

In general you'll want to fix the following:

• Remove default focus styles (these are handled by field-base)
• Remove borders and background-color.
• Set the width to 100%.
• Inherit cursor and color styles from field-base.

This would look something like this in CSS

input.styledInput {
  background: transparent;
  border: 0;
  box-sizing: border-box;
  color: inherit;
  cursor: inherit;
  outline: 0;
  width: 100%;
}

or in JavaScript

inputField.style.background = 'transparent';
inputField.style.border = '0';
inputField.style.boxSizing = 'border-box';
inputField.style.color = 'inherit';
inputField.style.cursor = 'inherit';
inputField.style.outline = 'none';
inputField.style.width = '100%';

Override Behaviour

Components that extend BaseComponent (such as this one) support the override prop which can be used to take finer control of a prop.

In cases where a component modifies it's own props (such as ak-field-base setting and removing focused), you may want to prevent this like so:

// React
render(){
  return <ak-field-base override={{ focused: getMyFocusedState() }} />;
}

// vanilla-JS
fieldBase.override = { focused: getMyFocusedState() };

Essentially, just pass in the props you need more control of into override rather than the prop itself and the component will never overwrite your value.

This means you'll also be responsible for setting it when neccessary. This usually involves listening to events like so:

let myFocusState = false;
/* ... */
render() {
  return <ak-field-base override={{ focused: myFocusState }} onBeforeFocusedChange={e => myFocusState = e.detail.focused}/>
}

This way, the component will tell you when it wants to update its props, without actually changing them.

Classes

FieldBase

FieldBase

Kind: global class

• Properties

  • fieldBase.appearance : string
  • fieldBase.label : string
  • fieldBase.hideLabel : boolean
  • fieldBase.invalid : boolean
  • fieldBase.focused : boolean
  • fieldBase.required : boolean
  • fieldBase.disabled : boolean
  • fieldBase.onLabelClick : function

new FieldBase()

Create instances of the component programmatically, or using markup.

Example

<FieldBase label="Email" />

fieldBase.appearance : string

The appearance of the field.

Valid values for this property are: 'standard' (default), 'compact' and 'subtle'.

Compact will make the field have less padding and subtle will remove the background/border until a user hovers over it.

Kind: instance property of FieldBase
Default: "standard"
Example

<FieldBase appearance="compact"></FieldBase>

fieldBase.label : string

The label to be rendered above the form field.

This prop is still required, even if the hideLabel prop is set as the label is also used to make the field accessible for screen readers.

Kind: instance property of FieldBase

fieldBase.hideLabel : boolean

Whether the field should show a label above it.

If set to true no label will be shown and no space will be reserved for it.

Note: You must still provide a label for the component regardless of this prop. The label is also used to make the field accessible to screen readers.

Defaults to false.

Kind: instance property of FieldBase
Example

<FieldBase label="First Name" hideLabel></FieldBase>

fieldBase.invalid : boolean

Whether or not a field should show a validation error.

This is shown to the user through a red border currently but will also include error messages in a future release.

Kind: instance property of FieldBase
Default: false
Example

<FieldBase invalid></FieldBase>

fieldBase.focused : boolean

Whether or not a field should show it's focused styles by default.

By default, this component will automatically add and remove this prop if itself or any child of it receives focus or blur events.

Kind: instance property of FieldBase
Default: false
HTML Example

<FieldBase invalid></FieldBase>

JS Example

field.invalid = true;

fieldBase.required : boolean

Whether or not the field is required.

If set to true, an asterisk will be appended to the label text.

Kind: instance property of FieldBase
Default: false
Example

<FieldBase label="First Name" required"></FieldBase>

fieldBase.disabled : boolean

Whether or not a field is disabled.

This is shown to the user through a disabled cursor icon when hovering over the field.

Kind: instance property of FieldBase
Default: false
Example

<FieldBase disabled></FieldBase>

fieldBase.onLabelClick : function

Callback that is called whenever the Label is clicked

Kind: instance property of FieldBase
Default: () => void
Example

<FieldBase onLabelClick={() => alert('label click!')} />

default : enum

FieldBase appearances values.

Kind: global enum
Properties

Support and feedback

We're here to help!

Let us know what you think of our components and docs, your feedback is really important for us.

Community support

Ask a question in our forum.

Check if someone has already asked the same question before.

Create a support ticket

Are you in trouble? Let us know!