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.

FieldBase ⇐ ComponentBase

Kind: global class
Extends: ComponentBase

• Properties

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

• Events

  • "beforeFocusedChange"
  • "labelClick"

new FieldBase()

Create instances of the component programmatically, or using markup.

HTML Example

<ak-field-base label="Email" />

JS Example

import FieldBase from 'ak-field-base';

const field = new FieldBase();
field.label = 'Email';
document.body.appendChild(field);

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"
HTML Example

<ak-field-base appearance="compact"></ak-field-base>

JS Example

field.appearance = 'compact';

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
HTML Example

<ak-field-base label="First Name" hideLabel></ak-field-base>

JS Example

field.label = 'First Name';
field.hideLabel = true;

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
HTML Example

<ak-field-base invalid></ak-field-base>

JS Example

field.invalid = true;

fieldBase.focused : boolean

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

By default, this component will automatically add and remove this prop if itself or any child of it receives focus or blur events. You can override this behaviour by using the override prop.

See Override behaviour for more information.

Kind: instance property of FieldBase
Default: false
HTML Example

<ak-field-base invalid></ak-field-base>

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
HTML Example

<ak-field-base label="First Name" required"></ak-field-base>

JS Example

field.required = true;

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
HTML Example

<ak-field-base disabled></ak-field-base>

JS Example

field.disabled = true;

"beforeFocusedChange"

This event gets emitted before a field-base changes it's own focused prop. (e.g. when a child element receives focus, field-base will set it's own focused prop).

It is cancelable. If it gets cancelled, the change is aborted.

It will not get called if the prop change came from somewhere else.

Kind: event emitted by FieldBase
HTML Example

<ak-field-base
  onBeforeFocusedChange={(e) => console.log('Just about to start the remove animation')}
></ak-tag>

JS Example

import { events } from 'ak-field-base';

field.addEventListener(events.beforeFocusedChange, (e) => {
  console.log('Just about to apply focused=' + e.detail.focused);
  // e.preventDefault(); // this would stop change
});

"labelClick"

This event gets emitted when the field-base label is clicked.

Kind: event emitted by FieldBase
HTML Example

<ak-field-base
  onLabelClick={(e) => console.log('The label was clicked.')}
></ak-tag>

JS Example

import { events } from 'ak-field-base';

field.addEventListener(events.labelClick, (e) => {
  console.log('The label was clicked.');
});

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!